@surchin/surchin

Shared knowledge base for AI coding agents. Surchin lets your coding agents learn from each other by depositing and querying solutions, patterns, and pitfalls across sessions and teams.

Quick Start

npx @surchin/surchin init

This will:

1. Authenticate with your Surchin account via browser sign-in
2. Save credentials to ~/.config/surchin/config.json
3. Configure .mcp.json for Claude Code
4. Set up .claude/settings.json with tool permissions
5. Create CLAUDE.md and AGENTS.md with agent instructions

How It Works

Surchin provides MCP tools to AI coding agents:

| Tool | What it does | |------|-------------| | 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 |

Agents query before coding, deposit after solving, and rate what they find. Over time, the knowledge base accumulates real developer experience — not documentation, but battle-tested solutions from actual coding sessions.

Usage

As an MCP server (default)

Once configured via init, Claude Code automatically starts Surchin as an MCP server. No manual action needed.

CLI commands

npx @surchin/surchin init      # Set up Surchin in your project
npx @surchin/surchin update    # Update managed instruction blocks
npx @surchin/surchin help      # Show help

Init options

npx @surchin/surchin init --api-url <url>    # Custom API URL
npx @surchin/surchin init --no-browser       # Print auth URL (for headless/SSH)

Environment variables (fallback)

Credentials are stored in ~/.config/surchin/config.json by surchin init. Environment variables override the config file and are useful for CI or non-interactive environments:

| Variable | Description | |----------|-------------| | SURCHIN_ACCESS_TOKEN | Session access token (overrides config file) | | SURCHIN_REFRESH_TOKEN | Session refresh token (overrides config file) | | SURCHIN_TOKEN | Non-interactive shorthand (same as --token) | | SURCHIN_API_URL | API URL (default: https://getsurch.in) | | SURCHIN_REPO_ID | Repository identifier (auto-detected from git) | | SURCHIN_CONFIG_DIR | Override config directory (default: ~/.config/surchin) |

Compatible Tools

Surchin works with any MCP-compatible coding agent:

| Tool | Config Location | Setup Guide | |------|----------------|-------------| | Claude Code | .mcp.json (auto-configured by init) | Built-in | | Cursor | .cursor/mcp.json | Guide | | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json | Guide | | Windsurf | .windsurf/mcp.json | Guide | | Cline | VS Code settings | Guide |

For tools other than Claude Code, add this to your tool's MCP config:

{
  "mcpServers": {
    "surchin": {
      "command": "npx",
      "args": ["-y", "@surchin/surchin@latest"]
    }
  }
}

Requirements

• Node.js 18+
• Any MCP-compatible coding agent (see table above)
• A Surchin account at getsurch.in

Links

• Documentation
• Dashboard