god

CLI-first personal agent runtime for reusable skills, project context collection, and plan-first workflows.

The current MVP is intentionally plan-only: it classifies a task, loads runtime skills, collects bounded target-project context, creates a structured plan, persists run artifacts, and waits for explicit approval. It does not edit target project files.

Last reviewed: 2026-07-01

Current Status

This repository is the package root for the MVP. The npm package name is @andrewgolovanov/god, and the installed CLI command is god. Mutable runtime state lives in ~/.godmode by default, so the CLI can be run from any directory after install, build, or linking. Pass target projects with --project.

Future goals include an installer, Telegram/Web/Codex/MCP adapters, parallel task execution, implementation workflows, checks, commits, and PRs. Those are not part of the current MVP.

Requirements

• Node.js 22+
• pnpm 11+
• Optional remote provider key, saved by god setup or provided through env:
  • OPENAI_API_KEY
  • ANTHROPIC_API_KEY

Setup

Install from npm after the package is published:

npm install -g @andrewgolovanov/god
god doctor
god setup

The GitHub repo may remain private while the npm package is public. Anything included in the npm tarball is public after npm publish, so package contents are restricted with the files allowlist in package.json.

Local development setup:

pnpm install
npm run build
node dist/adapters/cli/main.js setup

Optional local global command:

pnpm link --global
god doctor

For local/offline planning:

node dist/adapters/cli/main.js setup --provider heuristic

For OpenAI:

node dist/adapters/cli/main.js setup --provider openai --model gpt-5.5 --reasoning xhigh

Interactive god setup also offers OpenAI model profiles and reasoning effort choices. Use xhigh for the "Extra high" reasoning level. If OPENAI_API_KEY is not available, setup can save it locally in <god-home>/secrets.env.

For Anthropic Claude:

node dist/adapters/cli/main.js setup --provider anthropic

Manage saved provider keys:

god secrets list
god secrets set openai
god secrets remove openai

Quick Use

Plan work for an existing project:

cd /path/to/target-project
god plan "task context"
god plan --project /path/to/other-project "task context"

When --project is omitted, god plan uses the current working directory as the target project.

Plan a new project:

god new "build a small personal notes CLI"

Approve a run:

god approve <run-id>

List runs and skills:

god runs
god skills list
god config
god doctor

Find and import skills:

god skills find react performance
god skills add vercel-labs/agent-skills@vercel-react-best-practices
god skills add https://github.com/obra/superpowers --skill brainstorming
god skills import /path/to/local/skill
god skills remove <skill-id>

During development, the same commands can be run through tsx:

pnpm run dev -- plan --project fixtures/projects/minimal-node --context fixtures/tasks/simple-feature.md
pnpm run dev -- plan "task context from the current project"

Use a custom runtime home when testing isolated state:

node dist/adapters/cli/main.js --god-home /tmp/god-home doctor
GOD_HOME=/tmp/god-home node dist/adapters/cli/main.js doctor

Key Docs

• CLI usage
• Runtime layout
• Implementation plan
• Architecture design

Development

npm run build
npm run test
npm run test:smoke
npm run pack:dry

The smoke test exercises setup, plan, approve, and new against fixture projects without calling real AI provider APIs.

Verify the npm tarball locally before publishing:

npm run pack:local
npm install --global --prefix /private/tmp/god-install ./andrewgolovanov-god-0.1.6.tgz
/private/tmp/god-install/bin/god --god-home /private/tmp/god-install-home doctor

Runtime Guarantees

• Target project files are not modified by the MVP.
• Run artifacts are stored under <god-home>/runs/<run-id>/.
• Local AI settings are stored in <god-home>/config.json.
• Saved provider API keys are stored in <god-home>/secrets.env, not in config.json.
• User-imported SKILL.md skills are stored under <god-home>/skills/imported/.
• Project-local AGENTS.md, .codex/AGENTS.md, .cursor/rules/*.mdc, .agents/skills, and .codex/skills are read during god plan without being copied into <god-home>.
• Default runtime home is ~/.godmode.
• Shell environment API keys override saved provider keys.
• Domain and application layers stay independent of CLI, filesystem, and SDK details.

Known Limits

• The npm package is prepared for public scoped publishing, but npm publish remains a manual release step.
• Current workflows stop at planning and approval.
• Skill update/check/lock workflows are future slices.
• Checks, implementation, commits, PRs, Telegram, Web/PWA, Codex plugin, MCP, SQLite, and background jobs are future slices.
• Ollama/local model support is deferred until the cloud-provider contract is stable.