Claude Code

Claude Code is the primary integration target for Surchin. The surchin init command configures everything automatically — MCP server, tool permissions, agent instructions, and hooks.

Installation

Run the init command in your project root:

npx @surchin/surchin init

This will:

Open your browser to sign in to your Surchin account
Save session tokens to ~/.config/surchin/config.json
Configure .mcp.json for Claude Code
Set up .claude/settings.json with tool permissions
Create CLAUDE.md and AGENTS.md with agent instructions

Init Options

npx @surchin/surchin init --api-url <url>    # Custom API URL (self-hosted)

Auto-Detection

Surchin automatically detects agent context from the environment:

Repository ID — detected from the git remote URL
Agent type — identified as Claude Code from the MCP transport
Session tracking — each Claude Code session is tracked for continuity

MCP Tools

Once configured, Claude Code has access to these MCP tools:

Tool	Description
`query_insights`	Search for solutions, patterns, and pitfalls before starting work
`deposit_insight`	Save knowledge after solving a problem or discovering a pattern
`rate_insight`	Signal whether a result was helpful or unhelpful
`set_preference`	Save persistent user preferences across sessions
`end_session`	End the current session with optional summary and handoff note
`get_session_history`	Get recent session history with summaries and handoff notes
`get_skill`	Retrieve a skill's full instructions by ID or name
`create_skill`	Create or update a skill with triggers
`list_groups`	List all groups accessible to the current user
`reconnect`	Re-authenticate when credentials expire

Claude Code Hooks

Surchin can integrate with Claude Code's hook system for automatic knowledge capture. Hooks run shell commands at specific points in the agent lifecycle without requiring explicit tool calls.

Hooks are installed via the Claude Code plugin, not by surchin init. To install:

claude plugin install @surchin/surchin

Available Hooks

Hook	When It Runs
`session-start`	When a new Claude Code session begins. Queries Surchin for relevant context to pre-load.
`session-end`	When a session ends. Captures session summary and deposits accumulated knowledge.
`turn-summary`	After each agent turn. Captures incremental context for mid-session deposits.
`auto-capture`	Automatically detects errors and patterns worth depositing without explicit agent action.

CLAUDE.md Managed Block

The surchin init command adds a managed block to your project's CLAUDE.md file. This block contains the agent workflow checklist that instructs Claude Code to query, deposit, and rate insights during every session.

The block is delimited by markers so it can be updated without touching the rest of your CLAUDE.md:

<!-- BEGIN SURCHIN MANAGED BLOCK v0.5.9 -->
## Surchin Knowledge Base

### Required Workflow -- Complete This Checklist

Your FIRST tool call must be `query_insights`. Do NOT read files first.

- [ ] **QUERY FIRST**: `query_insights` with task description
- [ ] **WORK**: Read files, diagnose, fix the problem
- [ ] **QUERY AGAIN**: `query_insights` with specific root cause
- [ ] **DEPOSIT**: `deposit_insight` with findings
- [ ] **RATE**: `rate_insight` for every insight returned
<!-- END SURCHIN MANAGED BLOCK -->

To update the managed block after a Surchin upgrade:

npx @surchin/surchin update

Permissions Setup

The init command configures .claude/settings.json to auto-approve Surchin MCP tool calls. This prevents Claude Code from asking for permission on every query or deposit:

{
  "permissions": {
    "allow": [
      "mcp__surchin__query_insights",
      "mcp__surchin__deposit_insight",
      "mcp__surchin__rate_insight",
      "mcp__surchin__set_preference",
      "mcp__surchin__end_session",
      "mcp__surchin__get_session_history"
    ]
  }
}

Environment Variables

Authentication is handled by surchin init, which stores session tokens in ~/.config/surchin/config.json. The following environment variables can override config file values:

Variable	Description
`SURCHIN_API_URL`	API URL override for self-hosted instances (default: `https://getsurch.in`)
`SURCHIN_REPO_ID`	Repository identifier (auto-detected from git)

Troubleshooting

Tools not appearing — Ensure .mcp.json exists in your project root and is valid JSON. Restart Claude Code.
"Unauthorized" errors — Re-authenticate with npx @surchin/surchin init
Server crashes — Try running manually: npx @surchin/surchin (should wait for stdin input)
Node.js version — Requires Node.js 18+. Check with node --version