Metadata-Version: 2.5
Name: coderio
Version: 0.4.3
Summary: A skill-driven coding agent — structural harness, foldable thinking TUI, deepagents engine.
Author: coderio contributors
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai-agent,cli,coding-agent,langchain,langgraph,llm,mcp,model-context-protocol,sandbox,skills,textual,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.11
Requires-Dist: ddgs>=4.0
Requires-Dist: deepagents>=0.6
Requires-Dist: httpx>=0.27
Requires-Dist: langchain-anthropic>=0.2
Requires-Dist: langchain-core>=0.3
Requires-Dist: langchain-openai>=0.2
Requires-Dist: langchain>=0.3
Requires-Dist: langgraph-checkpoint-sqlite>=2.0
Requires-Dist: langgraph>=0.2
Requires-Dist: pydantic>=2
Requires-Dist: rich>=13
Requires-Dist: textual>=0.40
Requires-Dist: tomli-w>=1.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.16; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: langchain-mcp-adapters>=0.3.2; extra == 'mcp'
Description-Content-Type: text/markdown

# coderio

[中文](README.md) | **English**

> The agent claims "done" without running the tests? coderio's harness stops it.
> A local coding agent with **native Zhipu GLM & StepFun Step coding-plan support** — four-tier permissions, layered sandbox, MCP, lifecycle hooks, and an interactive TUI.

![demo](demo.gif)

## Install

```bash
pip install coderio
coderio    # onboarding wizard on first launch (pick provider, paste API key, auto context-window probe)
```

Requires Python 3.11+; Git Bash on Windows. Linux / macOS supported.

## Why coderio

The shared weakness of coding agents: **the model says "I'm done" and you just have to trust it**. coderio turns that sentence into a structural constraint—

### The Four Gates: the agent can't lie to you

| Gate | Behavior |
|---|---|
| **VerifyGate** | Wrote code, never ran it, wants to finish → intercepted, forced to continue. Parses real exit codes — **a failing test run does NOT count as verified** |
| **CompletionGate** | Declares done with pending todos → intercepted |
| **GroundingGate** | Cites files it never read → intercepted |
| **PlanGate** | Writes code without a todo list → soft nudge |

Not a prompt-level soft rule — a system-level control based on tool-call ground truth. Claude Code and Codex don't have this.

### Native Chinese coding-plan support

Zhipu **GLM Coding Plan** and StepFun **Step Plan** work out of the box (direct Anthropic-protocol connection) — your subscription quota runs a local agent, no proxies, no middle layer. Also supports OpenAI / Anthropic / Ollama / any OpenAI-compatible endpoint, with multi-profile switching.

### Layered security, honestly stated

- Four permission tiers (plan read-only / confirm per-action / auto_edit / full)
- Command blacklist + whitelist (accident prevention); Linux bubblewrap OS sandbox (boundary enforcement)
- First-use repo-config trust confirmation (hostile-repo protection); web_fetch SSRF protection
- The blacklist/whitelist are **accident prevention, not adversarial defense** — adversarial protection comes from the sandbox + permissions; use a VM for hostile code

## Feature highlights

- **Interactive TUI**: streaming output, foldable thinking (Ctrl+O), collapsible TODO panel, vertical permission menu, task interruption (Esc), slash-command autocomplete, session management
- **Headless mode**: `coderio run "task"` one-shot execution (CI / scripts / benchmarks) with graded exit codes
- **MCP support**: connect external tools via `.mcp.json` (Claude Code-compatible format), managed with `coderio mcp`
- **Lifecycle hooks**: `[[hooks]]` run your commands at PreToolUse / PostToolUse / UserPromptSubmit (exit 2 = block) — IO contract compatible with Claude Code
- **Three-layer skills**: bundled + user + project, progressive disclosure saves context
- **Context governance**: auto-compaction (60% window trigger), large-block offload, sqlite checkpoints across turns
- **Subagents**: research (read-only, double-enforced) + general-purpose (inherits the main agent's full security stack)
- **Engineering discipline**: 850+ tests, 80% coverage, mypy hard gate, uv.lock, 3 OS × 2 Python CI matrix

<details>
<summary><b>Config example</b> (click to expand)</summary>

```toml
# ~/.coderio/config.toml
[model]
provider_id = "bigmodel_coding_plan"   # Zhipu/StepFun coding plan, or openai/anthropic/ollama/custom
default = "glm-5.2"

[tools]
permission_mode = "confirm"            # plan | confirm | auto_edit | full
sandbox_mode = "off"                   # off | job (resource limits) | write (Linux file-write isolation)

# Lifecycle hooks (Claude Code-compatible contract)
[[hooks]]
event = "PreToolUse"
matcher = "write_file|edit_file"
command = "python .hooks/protect.py"   # JSON on stdin; exit 2 = block
```

MCP, the sandbox 4-tuple, and more: [docs/coderio-architecture.md](docs/coderio-architecture.md).

</details>

## Common commands

```bash
coderio                                              # interactive TUI
coderio run "fix the failing test" --quiet           # headless one-shot
coderio run "task" --dangerously-skip-permissions    # full access (explicit opt-in)
coderio mcp add github --type http --url ...          # manage MCP
coderio skills install                               # install skill suites
```

Type `/` inside the TUI for all commands (/resume sessions, /mode permissions, /profile configs, /think unfold reasoning).

## Known limitations

- The Windows write-sandbox currently equals job mode (true isolation awaits the ACL work — documented honestly)
- Blacklist/whitelist are accident-prevention by design (regex can be bypassed by obfuscation); use the sandbox / a VM for adversarial scenarios

## Origin

A spare-time project, open-sourced as a working reference for developers building their own coding agents. The name is **code + rio** (the author's English name is Lion; "codelion" sounded odd).

## Contributing & License

Issues and PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). MIT License.
