Quickstart

Install

Run in your terminal. Requires uv. Use an upstream-supported Python release (3.11–3.14). The package still accepts Python 3.10 for compatibility, but upstream security support has ended.

uv tool install --upgrade selvedge
selvedge --version

Current release: Selvedge 0.3.16.

Use pip instead

Install in a virtual environment:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade selvedge

On Windows, activate with .venv\Scripts\Activate.ps1 in PowerShell. If your system calls Python python3, use that to create the environment. Start your editor from the activated terminal, or use the absolute path to selvedge-server in its MCP configuration.

Try a demo first

selvedge demo

The demo saves a rejected approach and retrieves it through a fresh connection to a temporary database. It does not write to your project. The demo requires Selvedge 0.3.12 or newer.

Connect your agent

Selvedge works with any agent that can call a local stdio MCP server or invoke its CLI. No particular brand or model provider is required. The presets below automate setup for some clients; they are not the compatibility limit.

Optional setup preset

Agent not listed? Connect another compatible agent with MCP or the CLI.

Requires Selvedge. Install →

selvedge setup --agent claude-code

Restart Claude Code in this project. Enable Selvedge’s tools if prompted.

Full Claude Code instructions →

What setup changes

Writes .mcp.json and CLAUDE.md, plus Claude Code lifecycle hooks. Already using the Selvedge plugin? Keep that installation instead. Setup asks before changes and backs up modified files.

Help us measure installs (optional)

This optional command repeats installation or upgrade, then sends Selvedge one confirmation after it succeeds. It shares only your selected agent and campaign labels, using a one-use code that expires after seven days. No project data is sent and ongoing product telemetry stays off. Privacy details.

For bash or zsh, with curl installed. The regular command above works without this confirmation.

selvedge setup --agent codex

Restart Codex in this project. Enable Selvedge’s tools if prompted.

Full Codex instructions →

What setup changes

Writes project .codex/config.toml and AGENTS.md. Open this project in Codex and trust it to load project configuration; review and trust its hooks with /hooks. Setup asks before changes and backs up modified files.

Help us measure installs (optional)

For bash or zsh, with curl installed. The regular command above works without this confirmation.

selvedge setup --agent copilot

Restart Copilot (VS Code Local) in this project. Enable Selvedge’s tools if prompted.

Full Copilot (VS Code Local) instructions →

What setup changes

Writes .vscode/mcp.json and .github/copilot-instructions.md. Use the VS Code Local harness, enable the server’s tools, and review Chat: Configure Hooks. Setup asks before changes and backs up modified files.

Help us measure installs (optional)

For bash or zsh, with curl installed. The regular command above works without this confirmation.

selvedge setup --agent cursor

Restart Cursor in this project. Enable Selvedge’s tools if prompted.

Full Cursor instructions →

What setup changes

Adds the server to ~/.cursor/mcp.json and instructions to this project’s .cursorrules. Setup asks before changes and backs up modified files.

Help us measure installs (optional)

For bash or zsh, with curl installed. The regular command above works without this confirmation.

selvedge setup --agent gemini

Restart Gemini CLI in this project. Enable Selvedge’s tools if prompted.

Full Gemini CLI instructions →

What setup changes

Writes this project’s .gemini/settings.json and GEMINI.md. Restart Gemini CLI in the project and approve the server if prompted. Setup asks before changes and backs up modified files.

Help us measure installs (optional)

For bash or zsh, with curl installed. The regular command above works without this confirmation.

selvedge setup --agent windsurf

Restart Windsurf in this project. Enable Selvedge’s tools if prompted.

Full Windsurf instructions →

What setup changes

Adds the server to ~/.codeium/windsurf/mcp_config.json and instructions to this project’s .windsurfrules. Setup asks before changes and backs up modified files.

Help us measure installs (optional)

For bash or zsh, with curl installed. The regular command above works without this confirmation.

JavaScript is off. Use your agent’s setup guide:

Claude Code

Codex

Copilot (VS Code Local)

Cursor

Gemini CLI

Windsurf

Check compatibility and lifecycle hooks →

Other compatible agents

For a client with local stdio MCP support:

Run selvedge init from your project folder.
Register a server named selvedge with command selvedge-server, using your client’s MCP settings format. Use the executable’s absolute path if it is not on the client’s PATH.
Set the server’s SELVEDGE_DB environment variable to the absolute path of your project’s .selvedge/selvedge.db if the client starts outside the project.
Run selvedge prompt and add its output to the instructions your agent reads. Restart the client and approve its tool permissions if needed.

Clients that only accept remote HTTP endpoints cannot connect directly to this local stdio server. If your agent has shell access, it can instead call selvedge log, selvedge prior-attempts and the other CLI commands. Both interfaces use the same local store.

Native lifecycle hooks are optional integrations and vary by client. A custom agent can use the MCP tools or CLI without one of the bundled hook adapters.

Save one decision

Paste this into your connected coding agent:

Use Selvedge to save one real decision from this project, including why we made it and any approach we rejected. Ask me if no decision is available; do not invent one. Show me the saved entity path and record ID.

Open a new session in the same project. Give your agent the saved entity path and ask it to retrieve the decision with prior_attempts. Check that the result matches what you saved.

Only decisions explicitly saved to Selvedge can be recalled.

Walk through the verification →

Need a hand?

My agent cannot find Selvedge or my saved decision

Run selvedge doctor and check your version.
Confirm selvedge-server is on your agent’s PATH. With uv, run uv tool update-shell, then restart your terminal and editor.
Restart your agent in this project and enable Selvedge’s tools. Codex needs a trusted project; Copilot uses VS Code Local in Agent mode.
Confirm both sessions use the same project database.
Ask the agent explicitly to use log_change, then look up the saved entity with prior_attempts.

Native lifecycle adapters are available for the six setup presets; capabilities and activation differ. Activate and verify your agent’s hooks.

Use the CLI to read history

selvedge status
selvedge prior-attempts users.api_key
selvedge history --since 7d
selvedge search "credentials"

Replace users.api_key with your saved entity path. Read commands support --json. See the CLI reference, MCP tools, and entity path guide.

Connect multiple agents or automate setup

Repeat --agent to connect several tools to one project. Without it, setup detects supported tools. Custom MCP entries raise a conflict; custom Codex TOML entries need manual reconciliation. --force never rewrites those entries.

For unattended setup:

selvedge setup --agent codex --non-interactive --yes

Without --yes, non-interactive setup is a dry run.

Share feedback

Trying this in a project you control? Join the voluntary feedback pilot. The discussion is public; share only redacted, non-sensitive notes.

You can also report that you recalled a decision in a new session. This is a voluntary self-report, not an automatic check. No project contents or contact details are sent.