Monitor

The problem

Day-to-day coding with models usually means bouncing between a chat UI, a terminal, and a pile of ad-hoc scripts.

I needed one harness for repository work (shell, structured tools, and planning), tuned to how I actually work, and another general-purpose agent product would not have given me that.

Why I built it

Day to day, I wanted a harness I could reach for inside a repo, where the agent acts through tools I designed and does not improvise with whatever a chat window happens to invent that day.

I wrote Monitor for my own daily work and customized it to my workflow. It is not meant to be a general-purpose product, so the choices below optimize for a daily path I trust.

What I built

Monitor ships a production entry point (monitor / python -m monitor) that opens an interactive REPL. It has built-in commands, LLM-callable tools (git, search, edit, tests, typecheck, memory, todos), macros, and task planning, and it can also run an optional local OpenAI-style HTTP server. Config lives under the platform user config directory, and project instructions resolve through AGENTS.md or MONITOR.md. Optional extras (voice, TTS, Chroma, and others) fail when you use the feature, so a missing extra never blocks REPL startup.

There is also an alternate OOP stack (monitor-oop) and a full-screen --tui mode. Both are experimental by design and exist for exploration, while day-to-day work stays on the production path.

You launch it with monitor or python -m monitor.

Three decisions

These are the three choices I would defend in a design review.

1. Production vs experiment stays explicit.

The one recommended path is src/monitor/. monitor-oop is labeled experimental and is not the daily entry, and --tui is experimental inside the same entry. Labeling things this way lets me evolve the architecture without lying to myself or to the README, because I can try a new stack without making it the thing I depend on tomorrow morning. I was counting on the harness staying trustworthy only while the recommended path is obvious and experimental work stays labeled. The failure I care about is an experiment drifting into the default when the README goes soft.

2. Deterministic edits come before the NL fallback.

The preferred order is create → str_replace → insert_at_line → bulk_replace → modify_source_code last. The model gets mechanical tools first, and natural-language editing is the escape hatch, because a precise replace is reviewable and reversible in a way a free-form rewrite is not. That order gives me edits I can trust in a diff, and I do not spend the session cleaning up surprise churn from chatty rewrites. I treated mechanical tools first as the fair default for repository work.

3. Tool surface and safety are designed, not dumped.

Tool profiles are minimal, coding (default), review, and full. Runtime rails include nested tool depth caps, repeated-call loop detection, per-path read budgets, and sub-agent write scoping. --check-config reports readiness without printing secrets, and the local server defaults to 127.0.0.1. Profiles exist so I do not hand the model every tool on every task. Coding gets the default set, while review and minimal stay smaller on purpose so each profile matches what the task needs. The rails are there because on a desk machine the threat that matters is an agent that loops, digs forever, or writes outside a scoped path. Localhost and secret-safe config checks follow the same idea, which is useful power with a firm limit on how far a bad run can reach.

Proof

You can read the architecture doc and walk the same boot path yourself.

The public repo and docs/ARCHITECTURE.md describe the same design in writing.

• The production and experimental entry points are documented and kept separate.
• The architecture doc spells out the edit tool order and the tool profiles.
• The runtime safety rails (depth, loop detection, write scoping) are documented.
• The repo has a pytest suite, and --check-config handles secret-safe readiness.

Why I built it this way

I hold the same boundaries in my iOS work. I want clear ownership and real persistence of intent, and I want a design a technical peer can judge quickly.

An explicit production path keeps experiments labeled, and putting mechanical edits first makes diffs reviewable. Profiles and rails put a bound on tool power. Holding Monitor to my iOS standards is what lets me trust a harness I use every day.

The code lives at github.com/rdegraci/monitor, and you can go back home from here.