claude-devstack-rig

Wire your AI coding tools into a working stack in one command.

npx claude-devstack-rig init .

No Python. No global installs required. Just Node 18+.

Typical first-time setup

# 1. Install devstack globally
npm install -g claude-devstack-rig

# 2. Generate all config files in your project
devstack init .

# 3. Open .devstack/seed.md and fill in your architecture decisions
#    (state management, API pattern, auth, database, etc.)

# 4. Push conventions into Ogham
devstack seed .

# 5. Verify everything is working
devstack doctor .

After step 5, open Claude Code in your project. It will automatically have:

• Graphify's codebase graph available via MCP
• Ogham's memory of your conventions available via MCP
• Pre-tool-use hooks that keep the graph up to date as you work

Install dependencies (devstack won't do this for you)

devstack detects and configures these tools — it does not install them. Run these once before your first devstack init.

Graphify

pip install graphify
graphify install

Ogham (optional — skip if you don't want a DB)

Ogham is a memory layer. It's optional — devstack works fine without it, and auto-skips Ogham config if it's not installed. You can also explicitly opt out at any time:

devstack init . --no-ogham

If you do want Ogham, it needs a database. Easiest option is a free Supabase project.

Embeddings: Ogham needs an embedding provider for semantic search. By default it uses OpenAI (OPENAI_API_KEY / Claude API key). To run fully locally with no API key, install Ollama instead:

# Install from https://ollama.ai, then:
ollama pull nomic-embed-text

devstack auto-detects Ollama — if it's running, Ogham is configured to use it automatically. If not, it falls back to OpenAI. Graphify does not use Ollama.

# Run init — it will prompt for these credentials:
#   SUPABASE_URL   → your project URL, e.g. https://xxxx.supabase.co
#   SUPABASE_KEY   → service role key (Settings → API in Supabase dashboard)
#   OPENAI_API_KEY → your Claude API key works here too
uvx --from ogham-mcp ogham init

# Then wire it into Claude Code:
claude mcp add ogham -- uvx ogham-mcp

If you prefer Neon or self-hosted Postgres:

# Prompts for:
#   DATABASE_URL   → postgresql://user:pass@host/db
#   OPENAI_API_KEY → (or other embedding provider)
uvx --from 'ogham-mcp[postgres]' ogham init

Claude Code

npm install -g @anthropic-ai/claude-code

# Verify:
claude --version

OpenCode (optional)

npm install -g opencode-ai

# Verify:
opencode --version

What this does

When you use AI coding assistants (Claude Code, OpenCode), they work best when they know your project's structure, can search your codebase semantically, and have memory of your architecture decisions. Getting three separate tools configured to do that together takes time. This CLI does it in one step.

Run devstack init . in any project directory. It detects which tools you have installed, then writes exactly the config files those tools need to work together.

The tools it wires up

Graphify

Builds a semantic graph of your codebase — files, functions, imports, and how they relate. Claude Code and OpenCode use this graph to navigate large codebases accurately instead of guessing based on filenames alone.

Why: Without it, AI assistants lose context in any project bigger than a few files. With it, they can find the right function across 500 files in milliseconds.

Ogham

A memory layer for your project. Stores architecture decisions, coding conventions, rejected approaches, and team rules as searchable memories that get injected into AI context automatically.

Why: Every conversation with an AI assistant starts from zero unless it has somewhere to look up "we use Zustand, not Redux" or "never mock the database in tests". Ogham is that somewhere.

Ollama + nomic-embed-text

Runs a local embedding model that powers semantic search in both Graphify and Ogham. Searches your codebase and memories by meaning, not just keywords.

Why: Keyword search finds getUserById. Semantic search finds getUserById, fetchUser, loadUserProfile, and resolveAccountOwner — all at once, because they mean the same thing.

Claude Code / OpenCode

The AI coding assistants themselves. devstack init writes their MCP config (which tools they can call) and hook config (which scripts run before/after tool use) so they automatically use Graphify and Ogham on every session.

Why: Without proper MCP and hook config, Claude Code doesn't know Graphify and Ogham exist. With it, every file read and every code change is automatically tracked and indexed.

Install

One-off use (no install):

npx claude-devstack-rig init .

Global install from npm:

npm install -g claude-devstack-rig

# To uninstall:
npm uninstall -g claude-devstack-rig

Local dev install (from this repo):

npm install          # install dependencies
npm run build        # compile TypeScript → dist/
npm link             # symlink `devstack` into your global PATH

# To remove the symlink when done:
npm unlink -g claude-devstack-rig

Commands

devstack init [dir]

Detects installed tools and generates config files for them.

devstack init .
devstack init /path/to/project

What it generates:

| File | Purpose | |------|---------| | .claude/mcp.json | Tells Claude Code which MCP servers (Graphify, Ogham) to connect to | | .claude/settings.json | Registers pre/post tool-use hooks so Graphify indexes every file change | | CLAUDE.md | Injects agent protocol instructions at the top of your project's Claude context | | opencode.json | Same as .claude/mcp.json but for OpenCode | | .devstack/seed.md | Template for you to fill in architecture decisions before seeding Ogham | | .devstack/config.json | Snapshot of what was detected and generated (used by devstack doctor) |

Options:

--force           Overwrite entries you may have manually customised
--editor <type>   Force output for a specific editor: claude | opencode | both
                  (default: auto-detected from installed CLIs)
--no-ogham        Skip Ogham config even if Ogham is installed
--no-graphify     Skip Graphify config even if Graphify is installed
--dry-run         Preview which files would be written without writing anything

devstack seed [dir]

Reads your project files and pushes conventions and decisions into Ogham as searchable memories. Safe to run multiple times — it deduplicates before storing.

devstack seed .
devstack seed . --dry-run        # Preview what would be stored
devstack seed . --file my.md     # Use a custom file instead of .devstack/seed.md

What it reads:

| Source | What it extracts | Memory type | |--------|-----------------|-------------| | package.json | Dependencies, test framework, package manager | convention | | tsconfig.json | Strict mode, target, module format, path aliases | convention | | .eslintrc / eslint.config.* | Style rules, extends, plugins | convention | | Dockerfile | Base image, exposed ports | infrastructure | | .env.example | Required variable names (never values) | infrastructure | | CLAUDE.md | Conventions section if present | convention | | .devstack/seed.md | Architecture decisions you filled in | decision | | .git/config | Remote URL, default branch | convention |

Workflow:

1. Run devstack init . first — it creates .devstack/seed.md
2. Open .devstack/seed.md and fill in the blanks (state management, API pattern, auth approach, etc.)
3. Run devstack seed . — it pushes everything into Ogham

From this point, every Claude Code session automatically has your conventions in context.

devstack doctor [dir]

Runs health checks across your entire stack and tells you what's working, what's missing, and exactly how to fix it.

devstack doctor .

Example output:

  devstack v0.1.0

  Tools
  ✅ Graphify       v0.4.9 installed
  ✅ Graph          graph.json (847 nodes, 2341 edges)
  ✅ Ogham          v0.6.1 installed, DB connected
  ✅ Memory         Ogham has 23 memories for this project
  ⚠️  Spec-kit      not installed (optional)
  ✅ Ollama         running, nomic-embed-text loaded
  ✅ Claude Code    installed
  ⚠️  OpenCode      not found (optional)

  Project
  ✅ Seed           .devstack/seed.md fully filled

  Config
  ✅ MCP            .claude/mcp.json configured (ogham, graphify)
  ✅ Hooks          .claude/settings.json has PreToolUse + PostToolUse
  ✅ CLAUDE.md      Agent Protocol section present
  ⚠️  opencode      opencode.json not found — devstack init . --editor both

  Status: 10/12 checks passed

Exit codes:

• 0 — all checks pass
• 1 — critical failures (missing MCP config, Graphify not installed)
• 2 — warnings only (optional tools not installed)

Suitable for use in CI: devstack doctor . || echo "Stack not configured"

Requirements

• Node.js 18+ — the only hard requirement for running devstack itself
• Graphify — pip install graphify && graphify install
• Ogham (optional) — uvx --from ogham-mcp ogham init (needs a Supabase or Neon DB). Skip with --no-ogham if you don't want the overhead.
• Ollama (optional, Ogham only) — local embedding provider for Ogham. If not present, Ogham falls back to OpenAI. Graphify does not use Ollama.
• Claude Code and/or OpenCode — at least one AI coding assistant

devstack init works even if none of the optional tools are installed — it detects what's present and only generates config for what you have.