python-agent-harness

A Python port of the Emacs gptel-agent-harness: an agent execution harness with completion supervision, context compaction, tool-result caching, plan/build modes, layered bash safety, session persistence, and a rich TUI.

Features

• Agent loop with FSM supervision — the model is nudged (max 2) when it tries to stop before the task is complete; the nudge counter resets on tool calls; tool results are sanitized so a failed call never strands the loop.
• Context management — CJK-aware token estimation, per-model context windows (deepseek-v4/glm-5.2 1M, gpt-5 400k, kimi-k2.7 256k, claude 200k, ...), self-calibrating estimates from API-reported input tokens, and automatic compaction at 70% usage that summarizes the conversation and resumes with the last user request.
• Tools — Agent (sub-agents), TodoWrite, Glob (git-aware), Grep (rg → git → grep), Read, Insert, Edit (incl. unified diffs), Write, Mkdir, Bash, Skill, Question, PlanExit — all OpenAI-compatible tool schemas.
• Tool cache — per-file mtime / per-directory TTL validity, write-through invalidation on edits, and per-epoch deduplication ([Cached: Read ... — same as earlier call, see above]).
• Plan / Build modes — plan mode is read-only except the per-session plan file; PlanExit switches back to build with an "execute the plan" prompt; sub-agents in plan mode receive the read-only reminder.
• Safety — forbidden paths (default /mnt/), catastrophic/destructive/ dangerous bash pattern tiers, per-session allow/deny memory, 300s command timeout, plan-mode read-only bash whitelist, and file snapshots with /undo /history.
• Sessions — auto-saved after every response to ~/.local/share/python-agent-harness/sessions/, LLM-generated titles (renames the file), restore / restore-latest / sessions commands.
• Commands — init (create/update AGENTS.md), review (uncommitted changes / commit / branch / PR), summary, and custom commands from prompts/commands/*.txt.
• Editing input — prompt_toolkit-backed multi-line editor with persistent history (Up/Down recall), Enter for a newline, Esc+Enter (or Alt+Enter) to submit.
• Diff rendering — Edit/Write tool calls capture a unified diff of the file change and render it inline (red/green) in the TUI, so file edits are visible without leaving the app.

Install

python -m venv venv
venv/bin/pip install rich httpx prompt_toolkit
venv/bin/pip install -e .

Configuration

LLM settings live in a TOML config file — no environment variables needed:

python-agent-harness config --init        # write ~/.config/python-agent-harness/config.toml
python-agent-harness config               # show effective settings (API key masked)

Edit ~/.config/python-agent-harness/config.toml:

[llm]
base_url = "https://api.deepseek.com/v1"   # any OpenAI-compatible endpoint
api_key  = "sk-..."
model    = "deepseek-chat"
reasoning_effort = "medium"                # "low" | "medium" | "high" (thinking models)
# backend = "DeepSeek"
# temperature = 0.0
# max_tokens  = 8192
# timeout     = 600.0

reasoning_effort is passed to the API as-is (omitted when unset), so you can use whatever your provider accepts ("low"/"medium"/"high" for OpenAI and compatible providers).

Precedence: code defaults < config file < OPENAI_* environment variables (env still wins if you set them, but nothing is required). Use a custom file with --config PATH (also settable via PYTHON_AGENT_HARNESS_CONFIG).

Usage

python-agent-harness run [project-dir]   # interactive TUI agent
python-agent-harness init [project]      # create/update AGENTS.md
python-agent-harness review [project] [commit|branch|PR]
python-agent-harness explain [project] [target]
python-agent-harness sessions            # list saved sessions
python-agent-harness restore --latest    # restore newest session

TUI slash commands: /plan /build /compact /undo /history /save /summary /exit.

Input editing: type your message, press Enter for a new line, and Esc then Enter (or Alt+Enter) to submit. Up/Down recall previous inputs from ~/.local/share/python-agent-harness/input_history. Ctrl-D quits; Ctrl-C cancels the current input or agent run without leaving the app.

Layout

python_agent_harness/
├── agent.py        agent loop (FSM, nudges, compaction)
├── fsm.py          state machine + supervision
├── client.py       OpenAI-compatible streaming client (httpx)
├── tokenizer.py    CJK-aware token estimation + calibration
├── safety.py       path guards + bash policy tiers
├── undo.py         file snapshots / undo
├── cache.py        tool-result cache + dedup
├── planmode.py     build/plan mode + plan file lifecycle
├── compaction.py   compact frame / anchored summary
├── session.py      session persistence + titles
├── harness.py      AgentSession (wiring hub)
├── commands.py     init/review/custom command definitions
├── cli.py          argparse entry points
├── tui.py          rich + prompt_toolkit TUI
├── diffrender.py   unified diff generation + rich rendering
└── tools/          tool implementations + registry

Tests

venv/bin/python -m unittest discover -s tests -v

Verification checklist (ported semantics)

• Nudge supervision with fail-closed dead-session budget
• Tool-result sanitization (None → error placeholder)
• Compaction: frame, epoch reset, resume last request
• Plan mode: read-only + plan-file writes only
• Bash tiers: catastrophic → plan gate → destructive → dangerous → run
• Cache dedup messages and write-through invalidation
• Session metadata round-trip and title sanitization