Your Claude Code

🤖 Claude Code Assistant

A minimalist AI coding assistant built with LangGraph and MCP (Model Context Protocol). This project demonstrates how to create a functional coding assistant with a clean architecture, stripping away the complexity to understand the core concepts.

Features

• StateGraph Workflow: Clean three-node architecture (userinput → modelresponse → tool_use)
• Persistent State: SQLite-based checkpointing for conversation history
• Local Tools: File operations, pytest integration, code search
• MCP Integration: Desktop Commander, DuckDuckGo, GitHub (optional)
• Rich Terminal UI: Colorful, hacker-style interface with emojis
• Debugging: Full conversation history tracking in SQLite

Quick Start

Prerequisites

• Python 3.11+
• uv (Python package manager)
• Docker (optional, for MCP servers)
• Anthropic API key

Installation

1. Clone and navigate to the project:

cd claude-code-tool

1. Set up environment variables:

cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY

1. Create virtual environment and install dependencies:

# uv will automatically create .venv and install dependencies
uv sync

1. Run the assistant:

uv run main.py

Usage

Once started, you'll see a colorful terminal interface. Try these commands:

Basic Commands

help          - Display help information
tools         - List all available tools
exit/quit/q   - Exit the assistant

Example Queries

"Show me the content of main.py"
"What tools do you have?"
"List all Python files in the current directory"
"Run the unit tests"
"Search for 'agent' in the codebase"
"Read the README file"

Available Tools

Local Tools (Built-in)

• read_file: Read file contents
• list_files: List directory contents
• write_file: Write content to a file
• run_pytest: Execute pytest tests
• search_files: Search for files by pattern
• getfileinfo: Get detailed file information

MCP Tools (Optional)

To enable MCP tools, you'll need to install the respective MCP servers:

Desktop Commander (File System Operations)

npm install -g @modelcontextprotocol/server-filesystem

DuckDuckGo (Web Search)

npm install -g @modelcontextprotocol/server-duckduckgo

GitHub (Repository Management)

npm install -g @modelcontextprotocol/server-github
# Set GITHUB_TOKEN in .env

Sandboxed Python (Docker-based)

# Build the Deno Docker image
docker build -t deno-docker:latest -f ./mcps/deno/Dockerfile ./mcps/deno

State Persistence & Debugging

All conversations are saved in checkpoints.db. You can inspect the state:

# View recent writes
sqlite3 checkpoints.db "SELECT * FROM writes LIMIT 5"

# View checkpoints
sqlite3 checkpoints.db "SELECT * FROM checkpoints LIMIT 5"

Configuration

Environment Variables

Create a .env file with:

# Required
ANTHROPIC_API_KEY=your_anthropic_api_key

# Optional
GITHUB_TOKEN=your_github_token

Customizing Tools

To add custom tools, edit tools/local_tools.py:

from langchain_core.tools import tool

@tool
def my_custom_tool(param: str) -> str:
    """Tool description"""
    # Your implementation
    return result

# Add to get_local_tools()
def get_local_tools():
    return [
        # ... existing tools
        my_custom_tool,
    ]

Project Structure

claude-code-tool/
├── main.py                 # Entry point
├── agent.py                # Core agent implementation
├── tools/
│   ├── __init__.py
│   ├── local_tools.py      # Local tool implementations
│   └── mcp_tools.py        # MCP tool integration
├── mcps/
│   └── deno/
│       └── Dockerfile      # Deno MCP container
├── pyproject.toml          # Dependencies
├── .env.example            # Environment template
├── .gitignore
└── README.md

UI Customization

The assistant uses Rich for terminal UI. Customize the appearance in agent.py:

• Banner: _display_welcome()
• Colors: Modify the style strings (e.g., [bold cyan])
• Panels: Adjust Panel() configurations

Testing

The assistant includes pytest integration. To test:

# Ask the assistant
"Run the unit tests"

# Or manually
uv run pytest -v

Security Considerations

• File Access: By default, tools can access the entire filesystem. Consider restricting access in production.
• Code Execution: The sandboxed Python MCP runs in Docker/Deno for isolation.
• API Keys: Never commit .env files. Use environment variables.
• Tool Permissions: Review tool descriptions and limit sensitive operations.

Contributing

Contributions are welcome! Areas for improvement:

• [ ] Add human-in-the-loop approval for destructive operations
• [ ] Implement RAG for personal notes (Notion, Obsidian)
• [ ] Add more MCP integrations
• [ ] Improve error handling and recovery
• [ ] Add conversation export/import
• [ ] Web UI interface

How It Works

StateGraph Flow

1. User Input: Collects user query
2. Model Response: Claude processes the input and decides whether to use tools
3. Tool Use (conditional): Executes tools if requested
4. Loop: Returns to model response with tool results, or back to user input

Checkpointing

LangGraph's SQLite checkpointer saves the entire conversation state after each step:

• Enables conversation resume after crashes
• Facilitates debugging and analysis
• Supports multi-turn context retention

MCP Integration

Model Context Protocol servers are spawned on-demand:

• Containers start when tools are invoked
• Process terminates after execution
• Minimal resource overhead
• Clean separation of concerns

Resources

• LangGraph Documentation
• Model Context Protocol
• Anthropic Claude API
• Rich Terminal Library

---

Happy Coding! 🚀

Questions or issues? Feel free to open an issue or contribute!

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AIAnytime
• Source: AIAnytime/Your-Claude-Code
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.