Exocortex

From disposable chats to durable project work

A chat session is a poor place to keep the state of a software project. Context runs out, workers finish at different times, and a new session has to reconstruct what happened. I built Exocortex to give AI-assisted work continuity outside the conversation.

The system turns terminal AI tools into persistent project agents with their own roles, memory, handoffs, and scoped responsibilities. I designed the architecture, implemented the runtime and product surfaces, and made the operational decisions; names such as Thread, Amber, and Manfred identify software roles and agent profiles, not human collaborators.

A control plane built from simple primitives

I chose tmux sessions, MCP tools, a Bun API, and filesystem-backed state rather than a heavyweight agent framework. The active distribution monorepo holds four substantive packages plus installable system assets:

• Exocortex Thread is the human-facing surface. A React 19/Vite/Zustand PWA with login and setup gates brings Thread dashboards, project views, chat, Forge progress, planning, notifications, and operational status into one interface.
• The Bun API owns the control plane. It serves authentication, files, project state, notifications, agent control, Forge progress, dashboards, and runtime integration.
• MCP layers drive the runtime. The macx-tmux package spawns, reads, messages, sleeps, kills, lists, and registers persistent sessions; a separate ccsession package adds Claude Code session awareness.

Project orchestrators turn briefs into specifications and implementation plans, then dispatch specialist execution agents. Plan files, queue state, session registries, diaries, and handoffs keep operational state outside any single conversation.

Delegate execution, retain review

1. A project brief becomes a scoped specification and implementation plan.
2. An orchestrator starts specialized sessions with a work directory, profile, and bounded capabilities.
3. Workers report progress, questions, and failures through signals and notifications; the orchestrator reads output, sends follow-up context, or puts a session into cooperative sleep instead of polling.
4. Human gates pause decisions that need review; approved work continues without losing the running session.
5. Diffs, tests, browser checks, and explicit handoffs provide review evidence before work is accepted.

The runtime classifies session output into actionable states — COMPLETE, QUESTION, NEED_HELP, TEST_FAILED, TYPE_ERROR, DONE, WORKING — so an orchestrator can tell a worker waiting on a decision from one still making progress. Waiting is a runtime operation, and memory is durable project records, not a promise that a model will remember.

The operational failures shaped the architecture

Running the system on real work surfaced coordination and lifecycle problems that a longer prompt could not solve: tmux tilde paths dispatching sessions into the wrong directory, Codex sessions displaying pasted prompts without submitting them until a delay separated paste from Enter, a launchd-started bridge poisoning the tmux server's environment for every later session, and a session monitor that labeled a real agent an orphan because it only searched direct children of a tmux → shell → model process tree.

I consolidated the fragmented system into a single distribution monorepo with an installer, setup flow, API, PWA, and runtime tools. Installer testing exposed interactive port collisions, IPv4/IPv6 localhost behavior, stale service-worker caching, and configuration read from the wrong location — fixes that made installation and upgrades deterministic rather than treating a successful script exit as proof of a usable system.

Working infrastructure, honest limits

Exocortex is the engineering and evaluation infrastructure behind my product work: persistent runtime management, memory and handoff protocols, review surfaces, and recovery-oriented observability. A persistent runtime needs cooperative sleep, wake-on-message, handoffs, liveness checks, and a clear policy for dead sessions — the system keeps a failed worker's task context available for retry and review rather than discarding it.

It is an actively evolving internal system, not an open-source product, a consumer launch, or a claim of fully autonomous reliability. Lifecycle behavior, watchdogs, and some always-on ideas remain iterative; human gates, verification, and handoffs remain part of how it operates.