1up

Find the right code. Ground the answer in source.

1up turns a repository or Git worktree into a local index ranked by meaning and text, and serves it to coding agents over MCP. It is for developers whose agents open with broad repository reads and burn tokens and time doing it: with 1up the agent starts from ranked, source-grounded evidence, hydrates only the spans it needs, then verifies symbols and likely impact — all from an index that never leaves your machine.

Use 1up if you want your agent's first move to be ranked, source-grounded discovery instead of a broad file sweep, and you are comfortable treating its ranked search and impact as strong leads to verify rather than exhaustive proofs.

• Measured, not promised. In one paired run — the same agent answering the same seven questions, with 1up versus without — 1up cut input tokens 44%, latency 42%, and cost 52%, and all seven cases were answered correctly both ways.
• Ranked by meaning and text. Hybrid vector, full-text, and symbol retrieval finds code by intent and returns exact, hydratable source spans, so the agent skips the opening file sweep.
• Local and private. The index is built and stored on your machine under .1up; only the evidence your agent selects is passed to its host.
• Nine focused MCP tools. One oneup server moves an agent from readiness to orientation, ranked discovery, exact evidence, symbol completeness, and advisory impact.
• Bounded on large repositories. Over-threshold monorepos are not indexed blindly; 1up reports facts and asks for a directory scope so the first index stays fast and predictable.

The warm-suite eval runs the same coding agent on the same seven code-comprehension and impact-analysis questions twice — once with the oneup MCP tools, once with only raw file reads and text search — and both must pass the same factual-accuracy and expected-file assertions. Latest paired run (2026-07-14):

Both variants answered all seven cases correctly; the with-1up agent averaged 8 tool calls per case. These are single paired runs, not confidence intervals — the harness, cases, and reproduction steps live in evals/README.md.

Two ways to get going. Both end with the oneup MCP server configured for your repository.

This is the fastest path to a useful result. Paste the prompt below into the MCP-capable coding agent you use for this repository and let it configure the project-scoped server:

# Configure 1up MCP for this repository.

1. If `1up` is not installed, run:
   `curl -fsSL https://1up.rp1.run/setup.sh | bash`
   Otherwise, run `1up update`.
2. Verify the install with `1up --version`.
3. Configure the `oneup` MCP server in project/workspace scope.
   - Server name: `oneup`
   - Command: `1up`
   - Args: `["mcp"]`
4. Use explicit `--path` config only when project/workspace config is not available.
5. Do not try to restart this active host or verify newly added MCP tools from it.
   If config changed, ask the user to restart/reload this host so it can load `oneup`, then approve
   or trust the server if prompted.
6. After reload, call `oneup_status` and follow its next action only if indexing is needed.
   Then call `oneup_overview`, search for a concrete code question with `oneup_search`, and hydrate
   the best result with `oneup_get`.

Prefer to run each step? The script installer supports Apple Silicon macOS and Linux on arm64 or x86_64:

curl -fsSL https://1up.rp1.run/setup.sh | bash

The URL is a redirect to the latest GitHub Release asset — fetch https://github.com/rp1-run/1up/releases/latest/download/setup.sh directly if you prefer to see the source. The installer places 1up in ~/.local/bin. If that directory is already on PATH, the command is ready immediately; otherwise follow the printed instruction or open a new shell. Verify the binary:

1up --version

Add this project/workspace MCP entry:

{
  "mcpServers": {
    "oneup": {
      "command": "1up",
      "args": ["mcp"]
    }
  }
}

Reload the host, approve or trust oneup if prompted, then call oneup_status and follow its next action.

Need host-specific syntax or a config review first? For Codex, Claude Code, Cursor, VS Code, Copilot, generic JSON clients, explicit-path config, and host approval details, use the focused docs/mcp-installation.md reference. Prefer project/workspace configuration with args = ["mcp"]. For user-global or static hosts, use an absolute repository or worktree path:

{
  "mcpServers": {
    "oneup": {
      "command": "/absolute/path/to/1up",
      "args": ["mcp", "--path", "/absolute/path/to/repo"]
    }
  }
}

Everything below is reference detail for when you want it: the tool surface, large-repository scoping, the data and security boundary, staying current, and fixes for common snags.

One oneup server exposes exactly nine focused tools. Together they move an agent from readiness to orientation, ranked discovery, and exact evidence:

Start with oneup_status, follow the returned oneup_start action only when needed, and use oneup_overview to get the shape of an unfamiliar repository. Keep raw file reads, rg, or find for exact literal verification after 1up has narrowed the scope.

Point 1up at a large monorepo and it stops before doing expensive, unbounded work. On a first index, repositories over the default 3,000-file threshold are not indexed in full without a scope. Instead, 1up reports repository facts and asks you to choose a repo-relative directory cone:

1up start --scope services/payments

The scope is persisted across branches and restarts, and includes cannot reach outside it. Once an index already has a scope, let the agent follow the ranked scope suggestions returned by oneup_start to widen or narrow it explicitly; the CLI --scope example above is for the first index, not an implicit widening command.

The index stays on your machine; selected evidence can still pass to the configured agent host. The full data, network, and security boundary is:

• Source-derived index data is stored locally under the repository's .1up state. Linked worktrees share the main worktree's physical index while keeping results scoped to the active worktree and branch context.
• MCP returns selected source evidence to the configured agent host. That host's own data handling and network policy still apply.
• Installation and updates contact GitHub. Most non-MCP CLI commands may also refresh a cached update check. The first explicit indexing action may download the all-MiniLM-L6-v2 model from Hugging Face. If embeddings are unavailable, search can degrade to full-text results.
• Built-in secret-path globs reduce accidental indexing of common key, environment, cloud, SSH, and credential files. They are not a secret scanner or a data-loss-prevention guarantee.
• 1up makes a best-effort write of .1up/.gitignore; do not commit .1up index data.
• Every MCP tool except oneup_start is annotated read-only. The start tool updates local index state; none of the tools edits source files or executes arbitrary shell commands.
• When a release publishes checksums, the installer and updater require the matching archive checksum. Provenance verification also runs when a supported verifier can reach a verdict. An unavailable, offline, or inconclusive verifier falls back to the checksum with a notice; a failed provenance verdict aborts the operation.

Keep the binary and its shared worktree index aligned. For the recommended script install, apply the version advertised on the stable update channel in place:

1up update

Force an immediate remote check before applying:

1up update --check && 1up update

All linked worktrees that share an index must use the same 1up version. After upgrading them, use 1up reindex only when the CLI reports an old, unreadable, or incompatible index schema; routine refresh belongs to 1up start or the action returned by the MCP server.

Most setup failures come down to PATH, host reload, repository scope, or version alignment.

command -v 1up
1up --version

The CLI exists for scripts, automation, and index debugging. Agents are the primary interface through the oneup_* MCP tools, and most humans only ever run the installer and 1up update. When you do want the shell, the same local index powers a compact lifecycle on macOS and Linux.

1up start
1up status
1up list
1up stop

1up search "where is authentication configured?"
1up get :RESULT_HANDLE
1up symbol AuthService --references
1up context src/auth.rs:120
1up impact --from-symbol AuthService

1up gc
1up gc --apply

Use the installer on its published targets; use the Windows archive directly.

There is no published Intel macOS build. On Windows the local binary supports indexing, search, and MCP use, but the background start / status / list / stop daemon workflow is Unix-only.

• MCP installation reference
• GitHub Releases
• Release history
• Contributing
• Building from source
• License

Apache 2.0. See LICENSE.