God Agent

Local control plane for managing coding-agent sessions.

Motivation

Coding agents are getting good enough to run multiple real workstreams at once, but the human workflow around them is still awkward. You end up juggling terminal tabs, remembering which agent owns which worktree, checking who is blocked, copying follow-up instructions around, and manually creating the scaffolding for every new task.

God Agent is an experiment in turning that mess into a small local operations layer. It does not try to replace coding agents or invent a complicated role system above them. The assumption is simpler: trust each coding agent to do its own job, and build a control plane that handles the boring coordination around them.

Vision

The goal is a local cockpit for agentic development:

• start a new coding-agent task with one short command
• create isolated git worktrees and branches automatically
• launch Claude Code or another coding agent in the right context
• track every active agent, worktree, branch, status, and recent event
• collect blocked questions into one inbox
• send follow-up instructions back to agents
• expose structured state through --json so a higher-level agent can reason about what is happening
• eventually integrate with cmux as the visual workspace/cockpit layer

In other words, the CLI is not the whole system. It is the remote control for a local daemon that keeps durable state, watches the workspace, and routes messages between you and the coding agents.

This repo currently ships a dependency-light Node CLI with two bins:

ga
god

The CLI talks to a local daemon over a Unix socket at ~/.god-agent/god.sock. The daemon owns durable state, agent events, worktree metadata, and launch adapters.

Quick start

From this repo:

npm install
npm run build
npm link
ga init
ga doctor
ga dashboard

Start a new coding-agent task from inside a git repo with at least one commit:

ga "fix login redirect"

That is shorthand for:

ga start "fix login redirect"

Commands

ga init
ga doctor [--json]
ga daemon
ga status [--json]
ga dashboard
ga start <prompt> [--name name] [--repo path] [--no-launch]
ga agents [--json]
ga inspect <agent> [--json]
ga inbox [--json]
ga send <agent> <message>
ga notify <status> <message>
ga fetch
ga events [--json]
ga diff <agent>
ga logs <agent>
ga stop <agent>
ga forget <agent> [--remove-worktree]
ga config [list|get|set]
ga service [status|install|uninstall|start|stop|restart|logs]
ga hooks [doctor|install|uninstall] [claude]

Development

npm run build
npm run smoke
npm run e2e
npm pack --dry-run

Source lives in src/**/*.ts; published/runtime files are compiled to dist.

Daemon, Alerts, And Hooks

ga is a thin client. The local daemon owns state, events, alert policy, and agent observation. By default, the CLI auto-starts the daemon when needed:

ga service status
ga service logs

On macOS, install it as a launchd service:

ga service install
ga service start
ga service stop

Notification behavior is configurable:

ga config list
ga config set notifications.desktop true
ga config set notifications.progress false
ga config set staleMinutes 30

The daemon sends desktop alerts for needs_input, done, failed, and stale events by default, with dedupe so the same blocker does not repeatedly ping you.

Claude Code hooks can bridge lifecycle events into the daemon:

ga hooks doctor claude
ga hooks install claude
ga hooks uninstall claude

The hook installer updates ~/.claude/settings.json and writes a timestamped backup before changing it.

Skills

The repo includes two compact agent skills:

• skills/god-agent-worker: for coding agents running inside a God Agent managed worktree. It explains ga fetch, ga notify progress, ga notify blocked, and ga notify done.
• skills/god-agent-operator: for an orchestrating agent that uses ga to start, monitor, message, inspect, and clean up worker agents.

These skills are intentionally small. The CLI remains the source of truth for runtime behavior; the skills teach agents the coordination contract.

Current transport model

• Agent to daemon: ga notify, ga hook, and future Claude Code hooks.
• Daemon to agent: durable per-agent inbox. cmux/PTY injection is an adapter boundary and can be filled in once the local cmux command/API shape is known.
• Launching: on macOS, ga start can open a Terminal window and run Claude Code inside the newly created worktree. If cmux is installed later, the adapter can become the preferred cockpit transport.

Agent prompt contract

Launched agents receive a short coordination contract:

• run ga notify progress "<message>" for meaningful progress
• run ga notify blocked "<question>" when blocked
• run ga notify done "<summary>" when ready for review
• run ga fetch periodically to read messages from the god agent