npm package: @surchin/surchin
Description: The context engineering platform for AI powered teams
Latest version: 0.5.12

# @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

```bash
npx @surchin/surchin init
```

This will:
1. Authenticate with your Surchin account (browser, email, or API key)
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

```bash
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

```bash
npx @surchin/surchin init --api-key <key>    # Skip interactive auth
npx @surchin/surchin init --api-url <url>    # Custom API URL
```

### 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_API_KEY` | API key (overrides config file) |
| `SURCHIN_API_URL` | API URL (default: `https://getsurch.in`) |
| `SURCHIN_REPO_ID` | Repository identifier (auto-detected from git) |

## Compatible Tools

Surchin works with any MCP-compatible coding agent:

| Tool | Config Location | Setup Guide |
|------|----------------|-------------|
| [Claude Code](https://claude.ai/code) | `.mcp.json` (auto-configured by `init`) | Built-in |
| [Cursor](https://cursor.com) | `.cursor/mcp.json` | [Guide](../../docs/integrations/cursor.md) |
| [Claude Desktop](https://claude.ai/download) | `~/Library/Application Support/Claude/claude_desktop_config.json` | [Guide](../../docs/integrations/claude-desktop.md) |
| [Windsurf](https://codeium.com/windsurf) | `.windsurf/mcp.json` | [Guide](../../docs/integrations/windsurf.md) |
| [Cline](https://github.com/cline/cline) | VS Code settings | [Guide](../../docs/integrations/cline.md) |

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

```json
{
  "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](https://getsurch.in)

## Links

- [Documentation](https://getsurch.in/docs)
- [Dashboard](https://getsurch.in)