Claude Code integration

Claude Code has native MCP support, making it the most natural client for Oka Reason.

Setup

1. Add to your MCP config

In ~/.claude/claude_code_config.json (or your project’s .claude/mcp.json):

{
  "mcpServers": {
    "oka": {
      "command": "npx",
      "args": ["-y", "@oka-core/reason"]
    }
  }
}

2. Authenticate

Start Claude Code and run the login tool:

> Use the login tool to authenticate with Oka

This opens your browser to id.oka.so where you sign in or create an account. Your token is stored locally and refreshes automatically.

Use whoami at any time to check your authentication status.

CI/CD or headless?

Set OKA_API_KEY in the env block instead. See API key auth.

3. Verify the connection

> /mcp

You should see oka listed with its 19 tools.

4. Add CLAUDE.md instructions

See CLAUDE.md patterns for the full guide. At minimum:

## Oka

- Start every task with `context` for the relevant area
- Record decisions with `decision`, not just `observe`
- Call `done` when finishing with outcome notes

Hooks integration

Claude Code supports hooks that run automatically on events. Use them to ensure Oka is always consulted:

Auto-context on session start

Create .claude/hooks/session-start.sh:

#!/bin/bash
# Automatically query Oka context at session start
echo "Remember to call context() for the area you're working on before starting."

Post-task reminder

You can also use Claude Code’s PostToolUse hook to remind agents to record their work when they finish significant operations.

Workflow patterns

The context-first workflow

1. User: "Fix the auth middleware race condition"
2. Agent calls: context("auth middleware race condition")
3. Agent receives: 3 learnings from prior sessions
   - "Race condition in concurrent JWT refresh — fix: mutex" (0.91)
   - "Auth middleware drops requests when token expires mid-flight" (0.78)
   - "The /refresh endpoint needs a distributed lock, not just in-process" (0.65)
4. Agent uses learnings to inform the fix
5. Agent calls: decision("Used distributed lock via Redis SETNX for /refresh")
6. Agent calls: done(task: "Fix auth race condition", outcome: "success")

The multi-session workflow

Oka shines when work spans multiple sessions:

Session 1: Agent explores auth module
  → observe("Auth uses Supabase JWTs, 1h expiry")
  → observe("No refresh token rotation — potential security gap")
  → deviation("Cannot add rotation without DB migration")

Session 2 (different agent, next day): Picks up auth work
  → context("auth") returns Session 1's observations
  → decision("Adding refresh token rotation with DB migration")
  → done(outcome: "success")

Session 3 (different engineer, next week): Related billing auth
  → context("auth JWT") returns consolidated learnings from Sessions 1+2
  → Avoids the pitfalls already discovered

Parallel agent workflows

When multiple agents work concurrently on related areas:

Agent A (auth refactor):
  → context("auth") → gets learnings
  → decision("Moving to JWK validation")
  → observe("Found undocumented dependency on session store")

Agent B (API gateway, running in parallel):
  → context("auth middleware") → gets Agent A's observations (after consolidation)
  → deviation("Gateway auth assumes session store — needs update for JWK")

The organizational intelligence compounds across parallel work.

Tips

• Use workspaces. Set OKA_WORKSPACE in your MCP config to match your project name. This scopes events and makes context queries precise.

• Feedback is cheap, impact is high. When context returns results, a quick feedback(id, useful: true) takes seconds and measurably improves future results.

• Don’t filter on read — let the ranking work. context("auth") with a broad topic and reasonable min_confidence (default 0.3) often returns more useful results than a very specific query. The hybrid search is surprisingly good at relevance ranking.