agentic-terminal-workbench

A lightweight CLI for chatting with OpenAI models - with optional Composio toolkits

$ composio-agent "What came first, the chicken or the egg?"
 
  ● Thinking...
 
  The question of what came first -the chicken or the egg -is one of
  the oldest philosophical puzzles. From a biological standpoint, the egg
  came first. Genetic mutations that led to the first true chicken would
  have occurred in the egg laid by a proto-chicken ancestor.
 
$ composio-agent --toolkits github "List my open PRs"
 
  ● Fetching from GitHub...
 
  You have 3 open pull requests:
  1. feat: add streaming support (#42) -opened 2 days ago
  2. fix: token counting edge case (#38) -opened 5 days ago
  3. docs: update CLI reference (#35) -opened 1 week ago

Key Features

Streaming responses - Real-time token-by-token output via Server-Sent Events
Interactive REPL - Persistent chat sessions with slash commands and color-coded output
Composio toolkits - Connect 250+ external APIs (GitHub, Gmail, Slack, and more) through a single --toolkits flag
Typed API wrapper - Minimal, typed interface around OpenAI for programmatic use
Token-aware context - Automatic context window management powered by tiktoken
Model switching - Swap between GPT-4o, GPT-4 Turbo, GPT-3.5, and more at runtime via /model

Installation

# Clone the repository
$ git clone https://github.com/shricodev/agentic-terminal-workbench.git
 
# Navigate to the directory
$ cd agentic-terminal-workbench
 
# Install dependencies
$ bun install

Note: Requires Node.js v18+ and Bun.

Quick Start

Set up your environment variables by copying the example file:

$ cp .env.example .env
# Then fill in your API keys in .env

Standard chat:

$ bun run cli -- "What came first, the chicken or the egg?"

Interactive mode:

$ bun run cli

With Composio toolkits:

$ bun run cli --toolkits github,gmail "List my unread emails"

Programmatic usage:

import { ChatGPTAPI } from "composio-agent";
 
const api = new ChatGPTAPI({
  apiKey: process.env.OPENAI_API_KEY!,
  model: "gpt-4o",
});
 
const res = await api.sendMessage("Write a concise summary of Composio.");
console.log(res.text);

Note: Streaming is not available when toolkits are enabled due to OpenAI Agents SDK limitations.

Configuration

Variable	Required	Description
`OPENAI_API_KEY`	Yes	Your OpenAI API key
`COMPOSIO_API_KEY`	No	Required when using `--toolkits`
`COMPOSIO_USER_ID`	No	Overrides the default Composio user ID
`COMPOSIO_CLI_DEBUG`	No	Set to `1` for verbose lifecycle logs

You can also pass --apiKey directly to the CLI, or use --model to override the model for a session.

CLI Reference

Usage:
  $ bun run cli -- [prompt]
 
Options:
  -k, --apiKey <key>        OpenAI API key
  -m, --model <model>       Model to use (e.g. gpt-4o)
  -t, --timeout <ms>        Timeout in milliseconds
  -s, --stream              Enable streaming (default: true)
      --toolkits <list>     Comma-separated Composio toolkits to load

Interactive Slash Commands

Command	Description
`/help`	Show available commands
`/model <name>`	Switch to a different model
`/model list`	Show the current model
`/toolkits <list>`	Change active toolkits (Composio mode)
`/toolkits list`	Show active toolkits
`/clear`	Clear the screen
`/quit` or `/exit`	Exit the session

How Composio Mode Works

When --toolkits is provided, the CLI initializes a Composio session, loads the selected toolkits, and runs an agent through the OpenAI Agents SDK. The agent executes tools internally and returns the final response. This gives the LLM access to real-world APIs -read emails, create GitHub issues, send Slack messages -all from your terminal.

Project Structure

src/
├── cli.ts                  CLI entrypoint with interactive REPL
├── gpt-api.ts              OpenAI chat completion wrapper
├── composio-agent.ts       Composio toolkit integration
├── types.ts                Shared TypeScript interfaces
├── utils.ts                Model validation & token limits
├── index.ts                Public API exports
├── fetch.ts                HTTP fetch helper
├── fetch-sse.ts            Server-Sent Events streaming
└── stream-async-iter.ts    Async iterable stream utilities

Development

# Watch mode
$ bun run dev
 
# Production build
$ bun run build
 
# Generate docs
$ bun run docs
 
# Run tests (format check)
$ bun run test

Credits

This project is built on top of these excellent open-source projects:

OpenAI -LLM provider
Composio -Toolkit integrations for AI agents
OpenAI Agents SDK -Agent orchestration
tiktoken -Token counting
cac -CLI argument parsing
chalk -Terminal styling
ora -Elegant terminal spinners

License

MIT

GitHub @shricodev