You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
**Lightweight Python coding-agent harness for building reliable autonomous coding agents.** — FSM-driven execution, OpenAI-compatible, made for daily use and easy customization.
5
+
**A lightweight Python coding-agent harness for building reliable autonomous coding agents.**
6
+
FSM-driven execution · OpenAI-compatible · built for daily use and easy customization
A terminal coding agent inspired by [gptel-agent-harness](https://github.com/beacoder/gptel-agent-harness) and [opencode](https://github.com/anomalyco/opencode): reads your repo, plans, edits files, runs commands, and verifies its own work — with only **three runtime dependencies** (`rich`, `httpx`, `prompt_toolkit`) and any OpenAI-compatible API. It ports opencode's prompts and behaviors (AGENTS.md discovery, plan/build modes, skills, sub-agents, todo tracking) while staying dependency-light.
14
+
A terminal coding agent that reads your codebase, plans changes, edits files, runs commands, and verifies its work.
15
+
16
+
`python-agent-harness` is inspired by [gptel-agent-harness](https://github.com/beacoder/gptel-agent-harness) and [opencode](https://github.com/anomalyco/opencode). It brings opencode's prompts and core behaviors—such as `AGENTS.md` discovery, plan/build modes, skills, sub-agents, and todo tracking—into a lightweight Python implementation with only **three runtime dependencies**:
17
+
18
+
-`rich`
19
+
-`httpx`
20
+
-`prompt_toolkit`
21
+
22
+
It works with any **OpenAI-compatible API** and is designed to be easy to inspect, customize, and use for everyday software development.
python-agent-harness run # launch the agent in your project dir
36
+
37
+
python-agent-harness config --init
38
+
python-agent-harness run
28
39
```
29
40
30
-
Edit `~/.config/python-agent-harness/config.json`, set `base_url`/`api_key`/`model`, and run. Optional: `pip install -e ".[mcp]"` for MCP server integration; `pip install -e ".[dev]"` for dev tooling.
41
+
Edit `~/.config/python-agent-harness/config.json` and set your `base_url`, `api_key`, and `model`.
42
+
43
+
Optional extras:
44
+
45
+
```sh
46
+
pip install -e ".[mcp]"# MCP server integration
47
+
pip install -e ".[dev]"# development tools
48
+
```
31
49
32
50
## Features
33
51
34
-
-**FSM-driven execution**(`WAIT`/`TOOL`/`TRET`/`SUPERVISE`/`DONE`/`ERRS`/`ABRT`) with completion supervision: the model is nudged (max 2) if it stops early; failed tool calls are sanitized and never strand the machine. Transient failures (429/5xx) retry with exponential backoff + jitter.
-**Real coding tools** — Agent (sub-agents), TodoWrite, Glob, Grep, Read, Insert, Edit (incl. unified diffs), Write, Mkdir, Bash, Skill, Question, PlanExit. Synchronous tools run one at a time; asynchronous ones (Bash, Agent) run concurrently in emitted order.
37
-
-**Plan / Build modes** — plan mode is read-only except the per-session plan file.
38
-
-**Sessions that survive** — auto-saved to `~/.local/share/python-agent-harness/sessions/` after every response, LLM-generated titles, `/restore --latest`,`/sessions`.
39
-
-**A TUI built for focus** — rich live interface with pinned status bar, Todos panel, inline red/green diff rendering for Edit/Write, `prompt_toolkit` editor (Esc+Enter to submit, Tab completion, history, Ctrl-D quits, Ctrl-C cancels without leaving the app).
40
-
-**MCP servers (optional)** — with the `[mcp]` extra, MCP tools become ordinary agent tools (`mcp__<server>__<tool>`); supports`stdio`, `streamable-http`, `sse` transports.
41
-
-**Slash commands** — `/init`, `/review`, `/explain`, plus custom commands from `prompts/commands/*.md`.
52
+
-**FSM-driven execution**— explicit `WAIT` / `TOOL` / `TRET` / `SUPERVISE` / `DONE` / `ERRS` / `ABRT` states. Completion supervision nudges the model when it stops early, while failed tool calls are sanitized so they never strand the agent. Transient API failures (`429` / `5xx`) retry with exponential backoff and jitter.
53
+
-**Context management** — CJK-aware token estimation, per-model context windows, and automatic compaction at 70% usage.
54
+
-**Coding tools** — `Agent`, `TodoWrite`, `Glob`, `Grep`, `Read`, `Insert`, `Edit` (including unified diffs), `Write`, `Mkdir`, `Bash`, `Skill`, `Question`, and `PlanExit`. Synchronous tools execute sequentially; asynchronous tools such as `Bash` and `Agent` can run concurrently while preserving emitted order.
55
+
-**Plan / Build modes** — plan mode is read-only except for the per-session plan file.
56
+
-**Persistent sessions** — sessions are automatically saved after every response to `~/.local/share/python-agent-harness/sessions/`, with LLM-generated titles and support for `/restore --latest` and`/sessions`.
57
+
-**Focused TUI** — a Rich-based interface with a pinned status bar, Todos panel, inline red/green diff rendering for `Edit` and `Write`, and a `prompt_toolkit` editor with history and completion. `Esc+Enter` submits, `Ctrl-D` quits, and `Ctrl-C` cancels without leaving the application.
58
+
-**MCP support** — optional MCP integration through the `[mcp]` extra. MCP tools become ordinary agent tools such as `mcp__<server>__<tool>`. Supports`stdio`, `streamable-http`, and`sse` transports.
59
+
-**Slash commands** — built-in `/init`, `/review`, `/explain`, and other commands, plus custom commands loaded from `prompts/commands/*.md`.
42
60
43
-
## Mini opencode
61
+
## Inspired by opencode
44
62
45
-
Most of [opencode](https://github.com/anomalyco/opencode)'s prompts and behaviors have been ported over, so the agent reasons and works like opencode while staying dependency-light.
63
+
Most of [opencode](https://github.com/anomalyco/opencode)'s prompts and core behaviors have been ported to this project. The goal is to retain its practical coding-agent workflow while keeping the implementation small, dependency-light, and easy to customize.
46
64
47
-
**Prompts extracted from opencode** (in `python_agent_harness/prompts/`):
65
+
### Prompt and behavior mapping
48
66
49
-
| opencode prompt | harness equivalent |
67
+
The following opencode prompts have corresponding implementations in `python-agent-harness`:
- Optional `llm` keys: `backend`, `temperature`, `max_tokens`, `timeout`, `reasoning_effort` (passed to the API as-is when set), `stream` (`run --no-stream` overrides).
96
-
-**`models`** — named LLM profiles for runtime switching via `/model` (in the TUI: no arg lists, name or number switches; `default` always restores the main `llm` settings). Each profile is a partial settings dict; unset keys inherit the main `llm`.
97
-
-**`subagent_llm`** — LLM for Agent-tool requests; every key optional, unset keys inherit main `llm`. Set `profile` to a name from `models` to reuse a profile; precedence: profile settings > explicit `subagent_llm` keys > main `llm` > env.
98
-
-**`paths.context_path` / `paths.skill_path`** — where to load context files / skills from. Unset means the project's own `<project>/contexts` and `<project>/skills`.
99
-
-**`mcp.servers`** — requires the `[mcp]` extra; each server is `{transport, command, args, env, url, headers, parallel, timeout, enabled}`.
- Custom config: `--config PATH` or `PYTHON_AGENT_HARNESS_CONFIG`.
102
-
- LLM request/response bodies are logged as JSON to `/tmp/python-agent-harness-<date>-<id>.json` (override dir with `LLM_LOG_DIR`); path printed at startup.
141
+
### Configuration options
142
+
143
+
-**`llm`** — main LLM configuration. Optional keys include `backend`, `temperature`, `max_tokens`, `timeout`, `reasoning_effort`, and `stream`. Values such as `reasoning_effort` are passed to the API as-is when set. `run --no-stream` overrides `stream`.
144
+
-**`models`** — named LLM profiles for runtime switching with `/model`. A profile is a partial settings dictionary; unset keys inherit from the main `llm`. `default` restores the main LLM configuration.
145
+
-**`subagent_llm`** — LLM configuration for `Agent` tool requests. Unset values inherit from the main `llm`. Set `profile` to reuse a profile from `models`. Precedence is: profile settings > explicit `subagent_llm` settings > main `llm` > environment variables.
146
+
-**`paths.context_path` / `paths.skill_path`** — locations from which to load context files and skills. When unset, the project-local `<project>/contexts` and `<project>/skills` directories are used.
147
+
-**`mcp.servers`** — MCP server configuration. Requires the `[mcp]` extra. Each server supports `transport`, `command`, `args`, `env`, `url`, `headers`, `parallel`, `timeout`, and `enabled`.
-**Custom config** — use `--config PATH` or `PYTHON_AGENT_HARNESS_CONFIG`.
150
+
-**LLM logging** — request and response bodies are logged as JSON to `/tmp/python-agent-harness-<date>-<id>.json`. Set `LLM_LOG_DIR` to change the directory. The log path is printed at startup.
103
151
104
152
## Usage
105
153
106
154
```sh
107
-
python-agent-harness run [project-dir]# interactive TUI agent
155
+
python-agent-harness run [project-dir]
108
156
```
109
157
110
-
| Command | What it does |
158
+
Launches the interactive TUI agent. If `project-dir` is omitted, the current directory is used.
159
+
160
+
### Slash commands
161
+
162
+
| Command | Description |
111
163
|---|---|
112
-
|`/plan` / `/build`|switch between read-only plan and build mode |
0 commit comments