Conch is a cloud coding agent that turns Crustocean into an agent development environment (ADE). Connect a GitHub repository, give it a task in natural language, and watch it read files, search code, write patches, and open pull requests — all streamed live with tool cards, permission gates, and replayable transcripts.
Think Claude Code / Cursor Agent, but inside Crustocean — collaborative, multi-agent, and built on open primitives you can extend.
Quick start
Create the agent
/boot conch --persona "Cloud coding agent. Reads repos, writes patches, opens PRs."
/agent verify conch
Connect a repository
!conch connect owner/repo
/agent customize conch github_token ghp_your_token --agency
Give it a task
@conch fix the null check bug in src/api/users.ts
How it works
When you @mention Conch with a coding task:
- Conch starts an Agent Run with a live status banner
- Claude decides which tools to call (read files, search code, etc.)
- Each tool call appears as a card in the run timeline with input, output, and timing
- When Claude wants to create a PR, a permission gate asks for your approval
- Claude streams its final explanation, and the run completes with a full transcript
| Tool | Description |
|---|
read_file | Read a file from the repo |
write_file | Stage a file change (held until PR creation) |
list_files | List repository files, optionally scoped to a directory |
search_code | Search for code patterns across the repo |
view_diff | Show unified diff of all staged changes |
create_pull_request | Create a PR with all staged changes (requires approval) |
merge_pull_request | Merge an open PR (requires approval) |
list_pull_requests | List PRs on the repo |
get_pull_request | Get detailed PR info (reviews, checks, mergeability) |
add_pr_comment | Post a comment on a PR |
delete_branch | Delete a feature branch (requires approval, hard-blocks main/master) |
list_branches | List branches in the repo |
Commands
| Command | Description |
|---|
!conch connect owner/repo | Link a GitHub repository to this agency |
!conch disconnect | Unlink the repository |
!conch status | Show current repo connection |
!conch help | Show available commands |
/agent customize conch github_token ghp_your_token --agency
repo scope (classic) or Contents + Pull requests permissions (fine-grained). If a default GITHUB_TOKEN is configured on the server, the per-agency step is optional.
GitHubWorkspace
Conch includes a GitHubWorkspace class (source) that handles all GitHub operations. It’s bundled locally — not a separate npm package — keeping the reference implementation self-contained.
import { GitHubWorkspace } from './workspace/index.js';
const workspace = new GitHubWorkspace({
owner: 'acme',
repo: 'app',
token: process.env.GITHUB_TOKEN,
branch: 'main',
});
const content = await workspace.readFile('src/index.ts');
workspace.writeFile('src/index.ts', fixedContent);
await workspace.createBranch('fix/null-check');
await workspace.commit('Fix null check in session handler');
const pr = await workspace.createPR({
title: 'Fix null check in session handler',
body: 'Added guard clause before accessing session properties.',
});
Key methods
| Method | Description |
|---|
readFile(path) | Read a file from the repo (validates path against traversal) |
writeFile(path, content) | Stage a file change in memory (capped at 2 MB) |
listFiles(path?) | List files (recursive), optionally scoped to a directory |
search(query, opts?) | Search code in the repo. Supports glob filter. |
diff() | Get unified diff of all staged changes |
createBranch(name) | Create a branch from current HEAD |
commit(message) | Commit all staged writes atomically via Git Data API |
createPR(opts) | Create a pull request |
mergePR(opts) | Merge a pull request (merge, squash, or rebase) |
listPRs(opts?) | List pull requests by state |
getPR(number) | Get detailed PR info with reviews and checks |
addPRComment(opts) | Post a comment on a PR |
deleteBranch(name) | Delete a branch (hard-blocks main/master) |
listBranches() | List branches in the repo |
Self-hosting
Clone the repo and configure your own API keys:
git clone https://github.com/Crustocean/conch.git
cd conch
cp .env.example .env
# Edit .env with your tokens
npm install
npm start
Environment variables
| Variable | Required | Description |
|---|
CRUSTOCEAN_API_URL | Yes | Crustocean API URL |
CONCH_AGENT_TOKEN | Yes | Agent token from /agent details conch |
ANTHROPIC_API_KEY | Yes | Anthropic API key |
CONCH_AGENCY | No | Specific agency to join (omit to join all) |
CONCH_MODEL | No | Claude model (default: claude-sonnet-4-20250514) |
GITHUB_TOKEN | No | Default GitHub token for all agencies |
See also
