TPT CLI

A native desktop shell for directing autonomous coding agents (claude, cline, kilo, or a local GGUF model) against a todo.md task file. You direct work at the section level — "run Section 2" — and the agent executes the whole section on its own; TPT CLI gives you real-time observability (live diffs, thought stream, terminal output) and safety nets (automatic git checkpointing, one-click rollback, file locking, retry-until-blocked).

See spec.txt for the full original design rationale. Note one deliberate divergence from it: the spec describes a Tauri + Svelte/React frontend, but the shipped tpt-app is a native Rust GUI built on an in-house toolkit (appfront-canvas/appfront-core) — there's no Tauri, no webview, no JS/TS in this repo.

Workspace

Crate	Role
tpt-core	todo.md parser/serializer, file watcher, advisory file lock
tpt-config	~/.tpt/config.toml schema, agent profiles, defaults
tpt-diff	Diff computation shared by the live diff viewer and retry context
tpt-git	Git checkpoint / rollback / timeline
tpt-agent	The orchestrator: spawns agent CLIs, JIT file context, retry logic, multi-agent coordination, local-model tool loop
tpt-inference	Optional local GGUF model inference (llama-cpp-2), feature-gated
tpt-app	The native desktop GUI
tpt-cli	Headless todo.md operations (read / mark-done / watch / infer)

Getting started

# Build (default features need no extra toolchain)
cargo build --workspace --locked

# Run the desktop app (needs a todo.md in the working directory)
cargo run -p tpt-app

# Or drive todo.md headlessly
cargo run -p tpt-cli -- read todo.md
cargo run -p tpt-cli -- mark-done todo.md --section 0 --task 0
cargo run -p tpt-cli -- watch todo.md

Configuration lives at ~/.tpt/config.toml (created with defaults on first run) — see spec.txt §13 for the full schema, or crates/tpt-config/src/lib.rs for the authoritative definition. Default agent profiles are provided for claude, cline, and kilo.

Local model inference (optional)

The local-models feature adds a GGUF-backed agent profile (AgentKind::LocalModel) via llama-cpp-2. It's feature-gated so the default build doesn't need a C++ toolchain:

cargo build --workspace --features local-models
cargo run -p tpt-cli --features local-models -- infer --profile <name> --prompt "..."

Building this feature requires cmake and libclang/MSVC Build Tools (for llama-cpp-2's bindgen build script) — confirm your machine has these before relying on it.

Testing

cargo test --workspace --locked

Run a single crate or test:

cargo test -p tpt-agent --test coordination
cargo test -p tpt-agent parallel_disjoint_edits_auto_merge_without_conflict

Known limitations

• Keyboard shortcuts (spec §14) aren't wired: the appfront-canvas GUI backend only dispatches click events, with no keyboard-event hook yet.
• todo.md's advisory file lock is only queried (to drive the "read-only" UI indicator), not acquired by any writer — a documented tradeoff, since the writer is usually the spawned agent CLI process itself, not this codebase.
• The local-model tool loop's command sandbox (tool_loop::ToolLoopConfig::sandbox) is a denylist of obviously destructive patterns, not a real sandbox — don't run it against an untrusted model without an additional OS-level sandbox if that matters for your threat model.