A complete implementation of Claude in the terminal.
Unlike other tools that aim to support all kinds of LLMs, tclaude is designed specifically for Claude. As such, Claude-specific features like caching, Claude-native web search or code execution are implemented correctly and fully.
- Interactive chat with resumable sessions, extended thinking, and tool use
- Built-in grounded web search, code execution, and file analysis
- MCP server support (both remote and local)
- Implement any custom tool in just a few lines of Python
- Automatic caching (makes Claude up to 10x cheaper!)
pip install tclaudeThen set the ANTHROPIC_API_KEY environment variable to your Claude API key and you are good to go.
Running tclaude opens a new chat session. You can also directly pass a prompt to start a session.
tclaude "How do I make great pasta?"
# or: echo "How do I make great pasta?" | tclaude
> Great pasta starts with quality ingredients and proper technique. ...Or use an outward pipe to integrate tclaude into unix workflows
git diff --staged | tclaude "Write a commit message for this diff." | xargs -0 git commit -mUpload files with -f
tclaude -f paper.pdf "Summarize this paper."
tclaude -f cat.png "Is this a dog?"Claude will use web search and server-side code execution when the request demands it:
tclaude "Tell me the factorials from 1 through 20."
> [Uses Python to compute the answer.]
tclaude "What is the state of the art in physically based rendering?"
> [Uses web search and responds with citations.]Once you're done chatting, the session will be automatically named and saved as <session-name>.json in the working directory.
You can resume the session with tclaude -s <session-name>.json or browse past sessions with fuzzy finding via tclaude -s.
Customize where sessions are saved by passing --sessions-dir <dir> or by setting the TCLAUDE_SESSIONS_DIR environment variable.
Enable thinking with --thinking
tclaude --thinking "Write a quine in C++."
> [Claude thinks about how to write a quine before responding.]Several commands are available to do other things than chatting with Claude, such as /download to download files previously created by Claude. Use /help to see a list of available commands.
If you'd like to customize the behavior of Claude (e.g. tell it to be brief, or give it background information), create ~/.configs/tclaude/roles/default.md.
The content of this file will be prepended as system prompt to all conversations.
If you'd like to load different system prompts on a case-by-case basis, you can pass them as
tclaude --role pirate.md "How do I make great pasta?"
> Ahoy there, matey! Ye be seekin' the secrets of craftin' the finest pasta this side of the Mediterranean, eh? ...Simply implement your tool as a function in src/tclaude/tools.py and it will be callable by Claude.
Make sure to document the tools' function thoroughly such that Claude uses it optimally.
To connect tclaude to MCP servers, create ~/.configs/tclaude/tclaude.toml with the servers' address and authentication info.
Two kinds of servers are supported:
-
Remote servers (e.g. remote-mcp-servers)
- Claude will connect directly to the server and use the tools it provides. The connection is not made by your machine.
- Remote servers are useful for tools that require a lot of resources or need to be run in a server environment.
- If the server needs authentication, it can be done via OAuth2 or a custom token.
-
Local servers (running on your machine or in an internal network)
- tclaude will connect to the MCP server via your machine and forward the tools to Claude.
- Local servers are useful for tools that require access to local resources (e.g. files on your machine).
- Two protocols are supported: STDIN (tclaude starts the server and pipes the input to it) and HTTPS (tclaude connects to the server via a URL).
Example MCP configuration for ~/.configs/tclaude/tclaude.toml:
[[mcp.local_servers]]
name = "filesystem"
command = "npx" # command and arguments to start the MCP server
args = [
"-y",
"@modelcontextprotocol/server-filesystem",
"~", # access to the home directory
]
# or: url = "http://localhost:3000" # if the server is already running
[[mcp.remote_servers]]
name = "example-mcp"
url = "https://example-server.modelcontextprotocol.io/sse"
authentication = "oauth2" # opens a browser window to authenticate on first use
# or: authentication = "none"
# or: authentication = "token", authorization_token = "<your-authorization-token>"
# Optional: restrict the tools that can be used with this MCP server
# tool_configuration.enabled = true
# tool_configuration.allowed_tools = [
# "example_tool_1",
# "example_tool_2",
# ]
[[mcp.remote_servers]]
name = "another-remote-mcp-server"
url = "..."GPLv3; see LICENSE for details.