Getting Started
Run Intertool locally and connect Claude Code.
Requirements
- Node.js 20 or newer
- pnpm
- Docker with Compose
Install
pnpm install
cp .env.example .env.localGenerate separate secrets for the Auth.js session and the signed web-to-API boundary:
openssl rand -base64 32Set DATABASE_URL, AUTH_URL, AUTH_SECRET, and WEB_INTERNAL_SECRET in .env.local. Set DEV_AUTH_BYPASS=true only for local development.
Start
docker compose up -d postgres
pnpm db:migrate
pnpm db:seed
pnpm devThe web dashboard runs at http://localhost:3000; REST and MCP run at http://localhost:3001. The local seed provides Alice and Bob in Acme plus Mallory in a separate organisation.
pnpm dev loads the root .env.local for both services. When deliberately using a different web port, set AUTH_URL/NEXTAUTH_URL and the GitHub OAuth callback URL to that same origin; otherwise GitHub will return to the wrong local port.
The local dev, migration, seed, and integration-test commands default to the Docker PostgreSQL URL. Export DATABASE_URL in the shell only when you deliberately want to target another database; an older value in .env.local does not override the local default.
During onboarding, register a repository using either owner/repository or its full https://github.com/owner/repository URL. Intertool stores the normalized repository name; it does not clone or read the repository.
Connect AI clients
Create a token from API tokens and export it locally. Create a separate token for each client so you can revoke one connection without interrupting the others.
For agent-guided setup, paste this into Codex, Claude Code, Copilot, Grok, or another capable coding agent:
Install the Intertool MCP for me. Read and follow the canonical instructions at https://intertool.sh/installThe client selector on the Intertool homepage prepares this prompt for Claude Code, Codex, GitHub Copilot, Grok, or another MCP client and links directly to the matching manual setup below.
The /install endpoint returns plain Markdown designed for agents. It tells the agent how to detect its client, merge Intertool into existing MCP configuration without overwriting other servers, keep token plaintext out of chat and git, and verify the installed tools.
ChatGPT desktop and Codex
The ChatGPT desktop app, Codex CLI, and Codex IDE extension share the MCP servers configured in ~/.codex/config.toml:
[mcp_servers.intertool]
url = "http://localhost:3001/mcp"
bearer_token_env_var = "INTERTOOL_API_TOKEN"Restart the app or extension, then use /mcp to confirm the connection.
Claude Code
Add .mcp.json to the target repository:
{
"mcpServers": {
"intertool": {
"type": "http",
"url": "${INTERTOOL_URL:-http://localhost:3001}/mcp",
"headers": {
"Authorization": "Bearer ${INTERTOOL_API_TOKEN}"
}
}
}
}export INTERTOOL_API_TOKEN="itk_..."Run /mcp in Claude Code to inspect the connection. Never commit the token.
GitHub Copilot
Copilot CLI can register the local server directly:
copilot mcp add --transport http \
--header "Authorization: Bearer $INTERTOOL_API_TOKEN" \
intertool http://localhost:3001/mcpFor Copilot cloud agent, add the deployed Intertool MCP endpoint in Repository settings → Copilot → MCP servers. Store the token as an Agents secret whose name begins with COPILOT_MCP_; do not put token plaintext in the MCP JSON.
Grok and other remote clients
In Grok, open Connectors, create a custom MCP connector, and enter your deployed Intertool /mcp URL with bearer-token authentication. Grok runs remotely and cannot reach localhost, so use a public HTTPS deployment or a secure tunnel.
Any MCP client that supports Streamable HTTP can connect to the same /mcp endpoint by sending Authorization: Bearer itk_....
Import your Codex memory
The same personal token can import the durable Markdown memory stored by Codex on this computer:
export INTERTOOL_API_TOKEN="itk_..."
pnpm memory:import:codexOpen My memory in the dashboard to search the imported documents. The import is private to your user and idempotent; run it again whenever local Codex memory changes. It does not publish anything to Team memory. See Personal memory for the exact boundary and source options.
Plugin
claude-plugin/ contains the Intertool plugin. It adds the MCP server, context-retrieval guidance, a short SessionStart instruction, and /intertool:remember.
claude plugin validate ./claude-pluginRetrieval progress
Intertool asks connected agents to say “Looking into Intertool…” before calling get_context or search_context, once per lookup when progress messages are supported. This guidance is included in the MCP tool descriptions, agent install instructions and Claude Code plugin. The client controls its built in tool status label, so the exact wording is not guaranteed.
Automatic memory capture
Once connected, Intertool asks your agent to save useful verified learnings with capture_memory without waiting for you to add them manually. Captures appear in My memory and can be recalled by the same user through recall_memory in later work. Team sharing still uses reviewed publication. This is agent initiated capture, not guaranteed background recording: the client must follow the connection instructions and allow the tool call. See Personal memory for the capture and privacy boundaries.
For reliable checks beyond MCP guidance, install the automatic memory adapter. Codex and Claude Code hooks retrieve context before each prompt and verify capture or a no learning decision before completion. Queued uploads retry after failures.