Metadata-Version: 2.4
Name: chcode
Version: 0.1.0
Summary: Terminal-based AI coding agent with typer+rich
Project-URL: Homepage, https://github.com/ScarletMercy/chcode
Project-URL: Repository, https://github.com/ScarletMercy/chcode
Project-URL: Issues, https://github.com/ScarletMercy/chcode/issues
Author-email: Flymo Han <minimizeball@foxmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,cli,coding-agent,langchain,rich,typer
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.13
Requires-Dist: aiofiles>=25.1.0
Requires-Dist: aiosqlite>=0.22.1
Requires-Dist: bs4>=0.0.2
Requires-Dist: charset-normalizer>=3.4.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: langchain-openai>=1.1.10
Requires-Dist: langchain>=1.2.10
Requires-Dist: langgraph-checkpoint-sqlite>=3.0.3
Requires-Dist: markdownify>=0.14.0
Requires-Dist: pillow>=12.2.0
Requires-Dist: prompt-toolkit>=3.0.0
Requires-Dist: psutil>=6.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: questionary>=2.1.0
Requires-Dist: rich>=13.9.0
Requires-Dist: tavily>=1.1.0
Requires-Dist: typer>=0.15.0
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.25.0; extra == 'test'
Requires-Dist: pytest-cov>=6.0.0; extra == 'test'
Requires-Dist: pytest-mock>=3.14.0; extra == 'test'
Requires-Dist: pytest-timeout>=2.3.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# ChCode

```
 ███████╗  ██╗   ██╗   ███████╗   ██████╗   █████╗     ████████╗
██╔═════╝  ██║   ██║  ██╔═════╝  ██╔═══██╗  ██╔══██╗   ██╔═════╝
██║        ████████║  ██║        ██║   ██║  ██║   ██╗  ████████╗
██║        ██╔═══██║  ██║        ██║   ██║  ██║  ██╔╝  ██╔═════╝
████████╗  ██║   ██║  ████████╗  ╚██████╔╝  █████╔═╝   ████████╗
 ╚══════╝  ╚═╝   ╚═╝   ╚══════╝   ╚═════╝   ╚════╝      ╚══════╝
```

Terminal-based AI coding agent, built with LangChain + Typer + Rich.

> **Why "ChCode"?** The original prototype was a tkinter + LangChain app called **chat-agent** (chagent). When it evolved into a CLI tool, the name became **ChCode** — chat-agent, meet code.

<details>
<summary>📸 chagent — the original tkinter prototype</summary>
<img src="https://raw.githubusercontent.com/ScarletMercy/chcode/main/assets/chagent.png" alt="chagent prototype" width="600"/>
</details>

> 6000+ lines of Python, 14 built-in tools, full session persistence, git-aware workflow.

![Python 3.13+](https://img.shields.io/badge/python-3.13%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)

[中文文档](README_zh.md)

<img src="https://raw.githubusercontent.com/ScarletMercy/chcode/main/assets/chcode.png" alt="ChCode main interface" width="800"/>

## Features

### Model Management

- Compatible with **all OpenAI-compatible APIs** (OpenAI, DeepSeek, Qwen, GLM, Claude via proxy, etc.)
- Built-in quick setup for **ModelScope**, **LongCat**, and major providers
- **ModelScope**: 2000 free model calls/day
- **LongCat**: 50M+ free tokens/day minimum
- First-run wizard with **env auto-detection** (scans `OPENAI_API_KEY`, `DEEPSEEK_API_KEY`, `ZHIPU_API_KEY`, `ModelScopeToken`, etc.)
- Native **reasoning/thinking model** support — thinking tokens displayed in real time
- Create / edit / switch models at runtime
- Per-model hyperparameter tuning (temperature, top_p, top_k, max_completion_tokens, stop_sequences, etc.)
- Automatic **retry with exponential backoff** (3/10/30/60s) and fallback model switching on persistent failure

### Vision & Multimodal

- Dedicated vision model configuration via `/vision` command (independent from main model)
- Image analysis with **automatic media encoding** and base64 embedding
- **Video support** — send videos directly to vision models for analysis (MP4, MOV, AVI, MKV, WebM)
- Automatic image resizing for oversized inputs
- Supported image formats: PNG, JPG, JPEG, GIF, BMP, WebP, TIFF

### Session & History

- **Persistent sessions** with SQLite-backed checkpoints (LangGraph)
- Session list, switch, rename, delete
- **Context compression** — auto-summarize when approaching token limit
- Real-time **context usage display** in status bar

### Git Integration

- Working directory **rolls back with message edits**
- Create **branches from any message** (fork)
- Edit / fork / delete history messages via `/messages`
- Checkpoint counter in status bar

### Human-in-the-Loop

- **Common mode** — every tool call requires approval, with diff preview for edits
- **YOLO mode** — auto-approve everything
- Toggle with `Tab` key or `/mode` command

### Work Environment Isolation

- Per-project `.chat/` directory for sessions, skills, agents
- Global `~/.chat/` for shared skills and settings
- `/workdir` to switch project root

### Cross-Platform

- **Windows** — defaults to Git Bash, falls back to PowerShell
- **Linux / Mac** — native bash/zsh
- Persistent shell sessions with **automatic CWD tracking**

### Rich Terminal UI

- Real-time **status bar** — context usage %, git checkpoint count, ModelScope API quota
- **Streaming output** with token-by-token rendering
- Slash command auto-completion
- Color-coded tool approval UI with **inline diff preview** for file edits

### Observability

- **LangSmith tracing** — toggle on/off via `/langsmith` command
- Auto-disable tracing on 429 rate limit with user notification

### Sub-Agent System

- Three built-in agent types: **Explore** (codebase search, read-only), **Plan** (architecture design), **General** (full-capability coding)
- **Parallel execution** — launch multiple agents concurrently for independent tasks
- Sub-agents run with **isolated context**, protecting the main conversation from context pollution
- **Custom agents** — define your own agent types in `.chat/agents/` with dedicated tools and instructions

### Skill System

- Install / delete / manage skills via `/skill`
- Skills are injected into system prompt via LangChain middleware
- Supports project-level and global skill directories

### ModelScope Rate Limit

- Real-time **API quota display** in status bar (daily limit remaining, per-model remaining)
- Auto-enabled when using ModelScope models

## Built-in Tools (14)

| Tool | Description |
|------|-------------|
| `read` | Read file content with line numbers and offset |
| `write` | Create or overwrite files |
| `edit` | Surgical string replacement in existing files |
| `glob` | Find files by name pattern |
| `grep` | Search file contents with regex |
| `list_dir` | Browse directory structure |
| `bash` | Execute shell commands (Git Bash / PowerShell / bash) |
| `load_skill` | Dynamically load skill instructions via middleware |
| `web_fetch` | Fetch and convert URL content to markdown |
| `web_search` | Web search via [Tavily](https://tavily.com) |
| `ask_user` | Single-select, multi-select, batch questions for user interaction |
| `agent` | Launch sub-agents (explore, plan, general-purpose, custom), supports parallel execution |
| `todo_write` | Structured task tracking for complex multi-step work |
| `vision` | Analyze images and videos via ModelScope vision models |

## Quick Start

### Install

```bash
# Option 1: Install with pip
pip install chcode

# Option 2: Install with uv (recommended)
uv tool install chcode

# Option 3: Install with pipx
pipx install chcode
```

### Run

```bash
# Start interactive session
chcode

# Start in YOLO mode
chcode --yolo

# Model management
chcode config new    # add new model
chcode config edit   # edit current model
chcode config switch # switch model
```

### First Run

On first launch, ChCode will:

1. Scan environment variables for known API keys
2. Guide you through model configuration
3. Optionally configure Tavily for web search

## Commands

| Command | Description |
|---------|-------------|
| `/new` | Start new session |
| `/history` | Browse and switch sessions |
| `/model` | Model management (new / edit / switch) |
| `/vision` | Visual model configuration |
| `/messages` | Edit / fork / delete history messages |
| `/compress` | Compress current session |
| `/skill` | Manage skills |
| `/search` | Configure Tavily API key |
| `/workdir` | Switch working directory |
| `/mode` | Toggle Common / YOLO mode |
| `/git` | Show git status |
| `/langsmith` | Toggle LangSmith tracing |
| `/tools` | List built-in tools |
| `/quit` | Exit |

## Keybindings

| Key | Action |
|-----|--------|
| `Enter` | Send message |
| `Ctrl+Enter` | New line |
| `Tab` | Toggle Common/YOLO mode (when input empty) |
| `Ctrl+C` | Interrupt generation |

## Why No MCP?

ChCode intentionally does not integrate MCP (Model Context Protocol). The combination of **Skills + CLI tools** covers 95%+ of real-world coding agent scenarios. Skills provide structured, reusable instructions injected via middleware — simpler, faster, and more portable than MCP servers.

## Architecture

```
chcode/
├── cli.py                  # Typer CLI entry
├── chat.py                 # REPL main loop, slash commands, HITL
├── agent_setup.py          # Agent construction, middleware, model retry with fallback
├── config.py               # Model config, Tavily, env detection
├── display.py              # Rich rendering, streaming, status bar
├── prompts.py              # Interactive prompts (select/confirm/text)
├── session.py              # Session manager (SQLite)
├── skill_manager.py        # Skill install/delete UI
├── agents/
│   ├── definitions.py      # Agent types (explore, plan, general)
│   ├── loader.py           # Load custom agents from .chat/agents/
│   └── runner.py           # Sub-agent execution with middleware
└── utils/
    ├── tools.py            # 14 built-in tools
    ├── shell/              # Shell abstraction (Bash/PowerShell providers)
    ├── enhanced_chat_openai.py  # Extended ChatOpenAI with reasoning support
    ├── git_manager.py      # Git checkpoint management
    ├── skill_loader.py     # Skill discovery and loading
    ├── modelscope_ratelimit.py  # ModelScope API rate limit monitor
    └── tool_result_pipeline.py  # Output truncation and budget enforcement
```

## License

MIT
