chcode 0.1.0__tar.gz

chcode-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

chcode-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,32 @@
+name: Test
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra test
+
+      - name: Run tests with coverage
+        run: uv run pytest --cov=chcode --cov-report=term-missing --cov-report=xml
+
+      - name: Upload coverage
+        if: matrix.os == 'ubuntu-latest'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage.xml

chcode-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+.idea/
+.claude/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.chat/
+.coverage

chcode-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flymo Han
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chcode-0.1.0/PKG-INFO

@@ -0,0 +1,275 @@
+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

chcode-0.1.0/README.md

@@ -0,0 +1,231 @@
+# 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