Skip to content
BranchesTags

Repository files navigation

Coding Agent

简体中文 · English

Coding Agent is a programming agent for local development workflows. Its agent runtime is implemented in Python, with both a terminal interface and an Electron + React desktop MVP.

It can read and modify project files, search code, execute shell commands, and stream model responses and tool progress to the interface. Conversations are stored as JSONL and support restoration, branches, and context compaction.

The project is in an early stage of development. The terminal application provides the broader feature set; the desktop runtime is connected and usable, while packaging and additional desktop features are still in progress.

Features

  • Streaming agent loop: processes model output, tool calls, tool results, and subsequent reasoning, with abort, steering, and follow-up support.
  • Built-in development and search tools: read, write, edit, grep, find, ls, bash, plus optional web_search.
  • Restorable sessions: stores messages and settings changes in append-only JSONL and tracks the active branch through an entry tree.
  • Context management: includes token estimation, summary compaction, and compact-and-retry after context overflow.
  • File-backed long-term memory: extracts stable preferences and confirmed project decisions, retrieves them by user and project, and persists YAML snapshots backed by append-only JSONL facts.
  • Multiple model providers: currently includes catalogs for DeepSeek and Z.AI Coding Plan (China).
  • Project context: discovers AGENTS.md, CLAUDE.md, skills, and prompt templates.
  • Terminal UI: renders Markdown, streaming content, tool cards, model selection, and line-based differential updates.
  • Desktop MVP: supports workspace selection, session history, streaming messages, tool approval, model switching, and a slash-command palette.
  • Cross-client Plan Mode: provides runtime-enforced observation tools, structured questions, immutable plan revisions, recovery states, and explicit execution confirmation shared by CLI and desktop.

Interfaces

Terminal

The terminal application is currently the primary entry point. It is designed to run directly inside a project directory and includes the complete interactive command set, project-context discovery, session branches, and exports.

Desktop

The desktop application uses Electron + React with the Python AgentSession running as a separate sidecar. The renderer has no direct access to the shell, filesystem, or API keys. Native operations cross a restricted Electron IPC bridge and a versioned NDJSON RPC boundary before reaching the Python runtime.

The desktop MVP currently supports:

  • Opening a local project and switching between saved sessions
  • Streaming response text and thinking content
  • Tool execution cards and result updates
  • Approval prompts for bash, write, and edit
  • A command palette that opens when / is entered
  • /help, /new, /model, /compact, /clear, /session, /plan, /cancel-plan, /execute-plan, and /memory

Requirements

Python runtime

  • Python 3.13 or newer
  • uv
  • Windows, Linux, or macOS
  • Git for Windows is recommended; the application prefers Git Bash on Windows

Desktop development

  • Node.js
  • pnpm
  • A project virtual environment created by uv sync

Quick start

1. Clone and install dependencies

git clone https://github.com/SSK988I/Coding-agent.git
cd Coding-agent
uv sync

2. Configure provider credentials

DeepSeek:

$env:DEEPSEEK_API_KEY = "your API key"

Z.AI Coding Plan:

$env:ZAI_CODING_CN_API_KEY = "your API key"

You can also run /login from the terminal interface. Stored credentials are written to ~/.coding-agent/auth.json.

3. Start the terminal interface

uv run coding-agent

Start with an initial task:

uv run coding-agent "Read this project and explain its main modules"

4. Start the desktop application

cd apps/desktop
pnpm install
pnpm dev

Development mode uses the repository's .venv for the Python sidecar by default. To select a different Python executable:

$env:CODING_AGENT_PYTHON = "C:\path\to\python.exe"
pnpm dev

CLI usage

Help and model catalog

uv run coding-agent --help
uv run coding-agent --list-models
uv run coding-agent --provider zhipu --list-models

Non-interactive mode

Print only the final response:

uv run coding-agent -p "Inspect this project for potential issues"

Stream newline-delimited JSON events:

uv run coding-agent --mode json "Analyze packages/core"

Exit codes:

Code Meaning
0 Success
1 Model or request failure
2 Invalid arguments or missing input
130 User interruption

Session restoration

# Continue the latest session for the current project
uv run coding-agent --continue

# Open a session file or partial UUID
uv run coding-agent --session <path-or-session-id>

# Run without saving the session
uv run coding-agent --no-session

Plan Mode

Enter Plan Mode interactively with /plan, Shift+Tab, or Alt+M. Shift+Tab/Alt+M leaves Plan Mode by cancelling; it never executes a plan. Thinking-level cycling is Alt+T, while Ctrl+T only toggles thinking-block visibility.

For resumable non-interactive workflows:

uv run coding-agent --agent-mode plan -p "Plan the requested change"
uv run coding-agent --session <session-id> --answer-plan-question <question-id> "answer"
uv run coding-agent --session <session-id> --execute-plan <revision>
uv run coding-agent --session <session-id> --handoff-plan [revision]
uv run coding-agent --session <session-id> --cancel-plan

Plan State is reduced from the active JSONL v4 branch and can be resumed by either the CLI or desktop client. A bare /plan restores state-aware controls for drafting, pending questions, ready revisions, active execution, or recovery. Ready plans can be executed in place or handed to a clean child session for a second review; supplemental text returns the episode to drafting and never authorizes execution. settled means the Agent turn ended, not that its result was verified, and cancelling/stopping does not roll back effects already performed. See the Plan Mode Specification and architecture decision.

Provider and model selection

uv run coding-agent --model deepseek-v4-pro
uv run coding-agent --provider zhipu --model glm-5.2
uv run coding-agent --model zhipu/glm-5.2:high

Tool restrictions

# Enable only selected tools
uv run coding-agent --tools read,grep,find

# Disable shell execution
uv run coding-agent --exclude-tools bash

# Disable all tools
uv run coding-agent --no-tools

Web search

Web search is enabled by default and automatically follows the selected model:

  • DeepSeek uses the native server-side web_search tool through the Responses API and reuses DEEPSEEK_API_KEY; no separate search key is required.
  • Other models use the stored Zhipu Z.AI Coding Plan credential through the Web Search Prime Remote MCP fallback.

The welcome card reports the effective state as WEB on/off. Native DeepSeek search is counted as an available tool but does not open an MCP connection.

# Enable for this run only (overrides the persisted setting)
uv run coding-agent --web-search "Find the current stable Python release and cite official sources"

# Persist the setting for future sessions (enter this in the interactive UI)
/settings web_search_enabled true

# Explicitly disable for this run
uv run coding-agent --no-web-search

Queries are sent to the active search service and may consume DeepSeek API or Coding Plan MCP quota. Never include API keys, cookies, private code, internal URLs, or personal data. Search snippets are untrusted external data, and final answers should retain the returned source URLs.

File and image attachments

Prefix a path with @ to attach a text file or image to the initial message:

uv run coding-agent @README.md "Summarize this file"

uv run coding-agent --provider zhipu --model glm-5v-turbo `
  @screenshot.png "Analyze the problem in this screenshot"

Images can only be sent to models whose catalog entries declare image input support.

Built-in tools

Tool Purpose
read Read text files or images
write Create or overwrite files
edit Modify files by matching exact text fragments
grep Search file contents
find Find files by name or pattern
ls List directory contents
bash Execute shell commands
web_search Search the public web through native DeepSeek Responses or the configured Remote MCP fallback; enabled by default

Tools expose their name, description, JSON Schema parameters, and asynchronous execution method through a common interface. The agent runtime validates arguments before execution and emits start, update, and end events. Embedding frontends can use before/after hooks for approval, auditing, or result transformation.

Terminal commands

Command Description
/help Show commands and keybindings
/model Select a model from configured providers
/login, /logout Manage provider credentials
/new Start a new session
/plan, /cancel-plan, /execute-plan Open state-aware Plan controls, cancel, or explicitly execute
/session Show session information and statistics
/tree Inspect and switch session branches
/compact Compact context manually
/memory Inspect, toggle, forget, or clear long-term memory
/settings View or update persistent settings
/export Export HTML or JSONL
/copy Copy the latest assistant response
/hotkeys Show keyboard shortcuts
/quit Exit the application

The terminal editor provides slash-command completion. Entering / in the desktop composer opens a filterable command palette.

Long-term memory

Long-term memory is enabled by default. After a successful outer task, extraction uses only user-authored evidence, structured Plan answers, or the exact Plan revision the user explicitly executed. Tool output, assistant-only conclusions, Plan drafts, and compaction summaries are excluded. Relevant records are injected transiently before the next task and are never appended to the session JSONL.

/memory status
/memory list [--global|--project]
/memory conflicts
/memory forget <id-or-key> [--global|--project] --confirm
/memory clear --project --confirm
/memory clear --all --confirm
/memory on
/memory off

Memories are isolated by user and project. Forget and clear operations append tombstones so replaying old sessions cannot restore deleted values.

Sessions and configuration

The default data directory is ~/.coding-agent. Override it with CODING_AGENT_HOME:

~/.coding-agent/
├── auth.json        # Provider credentials
├── settings.json    # Model, thinking, retry, memory, and web-search settings
├── sessions/        # Per-project JSONL sessions
└── memory/          # User/project YAML snapshots and JSONL fact logs

Session files are append-only. In addition to user and assistant messages, they record model changes, thinking levels, compaction entries, and branch pointers so the active context can be restored after a restart.

If a task is interrupted before a tool finishes, the next LLM request inserts an error toolResult for the missing result at the model boundary. This prevents providers from rejecting an incomplete tool_calls history without overwriting the original JSONL file.

Architecture

Coding-agent/
├── apps/
│   └── desktop/                 # Electron + React desktop app
│       └── src/
│           ├── main/            # Electron main process and sidecar lifecycle
│           ├── preload/         # Restricted IPC bridge
│           ├── renderer/        # React interface
│           └── shared/          # Shared TypeScript types
└── packages/
    ├── llm/                     # Providers, models, messages, and SSE adapters
    ├── core/                    # Agent loop, tools, sessions, and compaction
    ├── tui/                     # Terminal components and renderer
    └── app/                     # CLI, AgentSession, and application runtime

The main desktop request path is:

React Renderer
    ↓ typed IPC
Electron Main / Preload
    ↓ versioned NDJSON RPC
Python DesktopRuntime
    ↓
AgentSession → Agent Loop → LLM Provider
    ↓                         ↓
Tool Runtime              SSE Events
    └──────────── events ─────┘

The core packages do not depend on a specific UI. The terminal and desktop applications share model adapters, the agent loop, tool execution, session restoration, and context compaction while implementing their own event presentation and interaction layers.

Development and validation

Python

uv sync
uv run ruff check .
uv run pyright --project pyrightconfig.release.json
uv run pytest -q
uv build --all-packages

Desktop

cd apps/desktop
pnpm install
pnpm typecheck
pnpm build

Security boundary

Coding Agent is not an operating-system sandbox. Once the model invokes a tool, it can read files, modify files, or execute commands with the permissions of the current user.

  • Enable project context files only in trusted repositories.
  • Use a container, virtual machine, or restricted account for unfamiliar projects.
  • Never commit API keys to the repository.
  • The desktop renderer does not hold API keys and cannot access the shell or filesystem directly.
  • bash, write, and edit require user approval in the desktop application by default.

See SECURITY.md for more information.

Contributing

Read CONTRIBUTING.md before submitting changes, and make sure the relevant tests, static checks, and type checks pass.

About

No description, website, or topics provided.

Resources

Readme

Contributing

Contributing

Security policy

Security policy
Activity

Stars

3 stars

Watchers

1 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages