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