https://github.com/damassi/agent-chat-cli
An agent chat CLI built on top of the new Claude Agent SDK
https://github.com/damassi/agent-chat-cli
Last synced: 9 months ago
JSON representation
An agent chat CLI built on top of the new Claude Agent SDK
- Host: GitHub
- URL: https://github.com/damassi/agent-chat-cli
- Owner: damassi
- Created: 2025-10-01T18:57:49.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-10-01T20:50:07.000Z (9 months ago)
- Last Synced: 2025-10-01T22:10:20.370Z (9 months ago)
- Language: TypeScript
- Homepage:
- Size: 27.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Agent Chat CLI
A bare-bones, terminal-based chat CLI built to explore the new [Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk/overview). Terminal rendering is built on top of [React Ink](https://github.com/vadimdemedes/ink).
The app has three modes:
- Interactive terminal app which communicates with LLM directly.
- Interactive terminal app _as a stand-alone MCP client_ with no direct LLM communication, serving as a frontend to the agent or other MCP servers.
- Stand-alone MCP server which clients can connect to, without TUI.
The agent, including MCP server setup, is configured in [agent-chat-cli.config.ts](agent-chat-cli.config.ts).
The MCP _client_ is configured in [mcp-client.config.ts](mcp-client.config.ts).
https://github.com/user-attachments/assets/00cfb9b6-ac65-4b95-8842-28ad0414ffd9
### Why?
This addresses a gap I’ve noticed in the ecosystem, where spinning up conversational LLM interfaces often comes with a lot of overhead. For example:
- One shouldn’t need to use VS Code, Claude, or Claude Code to interact with MCP servers, with all their abundance of features.
- How does one fine-tune behavior without expanding already long CLAUDE.md scripts (and similar configuration files)?
- What if the MCP server you’re interacting with is already an agent connected to an LLM? In that case, you incur a double tax - both in terms of latency and token expense - where responses are computed on the server and then re-computed by the client LLM. [MCP Sampling](https://modelcontextprotocol.io/specification/2025-06-18/client/sampling) is not yet widely supported.
- It’s hard to find lightweight, terminal-based chat UIs, and even harder to find terminal-based MCP _clients_, disconnected from an LLM.
This project aims to simplify things. It can run as an agent with simple UX, connected to an LLM, or as a stand-alone MCP pass-through client, sharing the same UX architecture, which communicate with an external MCP endpoint or stdio server to avoid double spends.
### Setup
1. Install dependencies:
```bash
bun install
```
2. Configure environment variables:
```bash
cp .env.example .env
```
Then edit `.env` and fill in the required values.
3. Update `agent-chat-cli.config.ts` with MCP data-sources. System prompts for data-sources live in `src/prompts`.
OAuth support works out of the box via `mcp-remote`:
See the config above for an example.
### Usage
#### Interactive Agent Mode
Run the agent in interactive terminal mode:
```bash
bun start
```
You'll see a prompt where you can type your questions or requests.
Type `exit` to quit.
#### Interactive MCP Client
To run as an MCP client (connecting to an MCP server):
```bash
bun start:client
```
By default it will launch the MCP stdio server in the background (ie, `bun server`).
Configure the MCP server connection in `mcp-client.config.ts`. HTTP is also supported.
#### MCP Server Mode
Run as a stand-alone MCP server, using one of two modes:
```bash
bun server
bun server:http
```
The server exposes an `ask_agent` tool that other MCP clients can use to interact with the agent. The agent has access to all configured MCP servers and can use their tools.
### Configuration
MCP servers and system prompts are configured in `agent-chat-cli.config.ts`.
To add specific instructions for each MCP server, create a markdown file in `src/prompts` and reference it in `agent-chat-cli.config.ts`:
```ts
const config = {
mcpServers: {
fooServer: {
command: "npx",
args: ["..."],
prompt: getPrompt("my-prompt.md"),
},
},
}
```