CodingAgent 是一个本地 Python 编码代理，具有文本终端界面和无头 CLI。它通过选定的工作目录运行 LLM 支持的编码任务，通过编排层暴露文件、补丁、shell、仓库、LSP、规划、内存和验证工具。

本文档由实时代码库生成。关于架构，请参见 ARCHITECTURE.md。关于当前的工程评估，请参见 docs/audit/2026-10-09-engineering-audit.md。

要求

• Python 3.11 或更高版本
• 配置好的模型提供者。提供者配置可从src/config/providers.json和用户偏好中加载。
• 支持HTTP/SSE/WebSocket的可选服务器依赖：pip install -e '.[server]'

安装应用程序和开发依赖：

项目元数据是依赖的权威。requirements.txt 存在于遗留启动脚本中，但不保证匹配包约束。

跑

启动终端界面：

运行一个任务时不使用界面：

创建项目-本地代理工作空间：

init 创建包含代理配置、钩子和项目指令文件的 .codingAgent/。使用 codingagent --help 表示完整的命令表面。

CodingAgent

CodingAgent is a local Python coding agent with a Textual terminal UI and a headless CLI. It runs LLM-backed coding tasks against a selected working directory, exposing file, patch, shell, repository, LSP, planning, memory, and verification tools through an orchestration layer.

This document is generated from the live codebase. For architecture, see ARCHITECTURE.md. For the current engineering assessment, see docs/audit/2026-10-09-engineering-audit.md.

Requirements

• Python 3.11 or later
• A configured model provider. Provider configuration is loaded from src/config/providers.json and user preferences.
• Optional server dependencies for HTTP/SSE/WebSocket support: pip install -e '.[server]'

Install the application and development dependencies:

python -m pip install -e '.[dev,server]'

The project metadata is authoritative for dependencies. requirements.txt exists for the legacy startup script and is not guaranteed to match the package constraints.

Run

Launch the terminal UI:

codingagent

Run one task without the UI:

codingagent --task "Explain the current repository structure" --workdir /path/to/repository

Start a project-local agent workspace:

codingagent init --dir /path/to/repository

init creates .codingAgent/ with agent configuration, hooks, and a project instruction file. Use codingagent --help for the complete command surface. Key commands include init, system-prompt, session, status, mcp, and diff.

Safety Model

Normal agent tool calls go through a centralized execution pipeline that applies tool normalization, permission checks, read-before-write rules, workspace checks, approval handling, validation, snapshots, hooks, and telemetry. Use the least permissive mode that satisfies the task:

codingagent --task "Inspect this repository" --permission-mode read_only
codingagent --task "Update one test" --permission-mode workspace_write
codingagent --task "Plan an upgrade" --dry-run

--autonomous does not approve gated tools unless their canonical names are explicitly passed with --autonomous-approve. Do not use --autonomous-approve '*' unless you accept every gated action.

Shell containment fails closed by default when an enforcing sandbox backend is unavailable (or can be configured via CODINGAGENT_SANDBOX_ALLOW_UNENFORCED=1). Treat server-enabled deployments as trusted local use only.

Test And Quality Commands

python -m pytest tests/unit -q -p no:logging
python -m pytest tests/integration -q -p no:logging -m "not real_llm and not lmstudio and not ollama"
python -m ruff check src tests tui --select=E,F,W --ignore=E501