harness-workspace

Inspiration

Modern product work rarely lives in one repo. A single requirement can touch frontend, backend, and QA, each with different package managers, Node versions, and start scripts. Meanwhile AI agents still default to “open the main clone, run pnpm run dev, scan the whole tree”—and often analyze the wrong branch or worktree. We wanted something that sits under Claude/Codex rather than replacing them: an engineering workspace that keeps process files out of business repos, isolates every task with real Git worktrees, and always points CodeGraph at the correct working tree. Humans should still feel like “enter a folder, open the agent, commit”—not learn a second operating system of CLI verbs.

What it does

Harness Workspace is a file-first multi-repository workspace manager. You register repos where they already live, create a Task per requirement, and get isolated Git worktrees (identity unified as @, branch = task slug). Each working tree gets its own CodeGraph—no shared indexes, no silent fallback to base/main. Cross-repo links are modeled as relations; scripts own YAML sync, graph ensure, doctor, and lifecycle so agents stay low-context. Repo contracts capture real commands (e.g. pnpm run qa instead of deprecated dev) so automation doesn’t guess. Machine state hides under .harness/; people work under work// with a short human-facing surface. It does not auto-commit, push, or merge, and does not try to be an agent runtime.

How we built it

We built a Python 3.9+ CLI (harness) with a thin package core: workspace init, repository registry, task/worktree lifecycle, CodeGraph registry and strict task graph views, relations/trace, doctor, events, and knowledge (user-confirmed only). All machine-managed YAML is written atomically via Python (file locks, temp file + replace)—agents never hand-edit large config. Tests cover Git worktree flows, graph routing safety, contracts/run profiles, and CLI projections. Design docs (AGENTS.md, grok.md) lock product boundaries: file-first, zero intrusion into business repos, low agent context, minimal daily commands for humans.

Challenges we ran into

• Human path vs machine correctness: deep trees (tasks/active/…/worktrees/…/project) protect isolation but confuse people; we had to redesign toward work//@ and hide machinery in .harness/. • CodeGraph physical limits: indexes live under project .codegraph/; we couldn’t fake external DBs—so we model workspace adapters honestly and still enforce one graph per worktree. • Closing tasks without breaking the world: moving task directories on complete invalidates worktrees, graph roots, and open IDE windows—so stable paths + status-in-YAML became a hard requirement. • Agent command drift: agents keep inventing pnpm run dev; contracts, deprecations, and short outputs matter more than longer prompts. • Scope discipline: easy to become an agent gateway or chat memory platform; we repeatedly cut that to stay an engineering workspace.

Accomplishments that we're proud of

• A working multi-repo Task + worktree group with rollback on partial create failure. • Strict CodeGraph routing (repo@task), with doctor and ensure gates that refuse wrong or shared indexes. • YAML-as-state, Python-as-truth—atomic multi-file updates under concurrent agents. • Clear product boundaries: provider-agnostic, no auto-commit/push, no business-repo pollution. • Design convergence on identity unity (task / branch / directory / graph) and low-context CLI projections so AI doesn’t eat the whole workspace as prompt.

What we learned

Isolation without legible identity still fails people (terminal titles only show the last path segment). Scripts beat prompts for anything deterministic. “More CLI” is often worse UX than a simpler tree. Honest modeling of tool limits (CodeGraph, Git) beats claiming magic. The best AI-dev tooling often reduces what the model must know: short pointers, correct worktree, forbidden wrong commands—not a second memory system.

What's next for harness-workspace

Ship the human-facing layout (work/, stable task paths, @ names, branch = slug, TASK.md only). Harden repo contracts and optional graphs for backend/QA. Add harness where for identity checks. Keep process orchestration (bootstrap/up) script-first and optional. Explore UI maps for e2e without full-repo walks. Stay out of agent runtimes—double down on being the reliable multi-repo workspace layer every coding agent can stand on.

Built With

• ai-assisted-development
• codegraph
• developer-tools
• multi-repo
• python
• yaml