docs / getting started
getting started
scanning your repo
the fastest way to start is to scan a repo. runshift maps your codebase, flags security gaps and blast-radius files, and creates coordination rules for files, sessions, and risky actions.
npx runshift init
run this in any repo directory. the CLI reads your codebase locally and sends context to runshift. you'll get findings in your browser and the option to write coordination rules directly into the repo.
you can also scan from relay — type “scan my repo” and connect your GitHub account.
coordinate session
once your repo is scanned, runshift keeps agents aligned around the same context. connect Claude Code, Cursor, or any external agent via @runshift/connect.
coordination features: file locking (advisory and hard), session management, shared repo context, and gate rules by event type. multiple agents can work the same repo simultaneously without conflicts.
see the Claude Code integration guide to connect your first agent.
adding an agent
there are two ways to add an agent to your roster.
build an agent
use the wizard to create a native agent inside runshift. you define the identity, task, model, gate policy, skills, and schedule. runshift hosts and runs it. click the plus button in the roster to start.
connect via AMP
register an external agent using the Agent Message Protocol. your agent runs wherever you want. it signals runshift on every run using a per-agent API key. runshift tracks status, cost, and gates without touching your infrastructure.
relay commands
type commands into the relay chat panel to control agents. relay understands plain language, but these patterns work reliably:
scan my repo
starts a github repo scan. connect github if you haven't yet.
open a pr
opens a governance PR on the scanned repo after scan completes.
revert
closes the governance PR and reverts coordination rules.
run [agent-name]
triggers an agent with default behavior.
run [agent-name]: [input]
triggers an agent with a specific input.
stop [agent-name]
interrupts a running agent and marks the run as stopped.
examples:
scan my repo
run growth
run outreach: Jane Smith, Acme Corp
stop rover
trust gates
when an agent is about to take a consequential action, runshift interrupts execution and fires a gate.
you'll see an amber banner in the deck panel with the agent name, the proposed action, and a summary of what it's about to do. you can approve or deny.
gates also fire to Slack — you'll get a message in your configured channel with the draft content visible and approve/deny buttons that link back to the dashboard. you don't have to be at your desk to stay in the loop.
every gate decision is written to the audit trail. approvals, denials, and the content at the time of the decision — all immutable, all queryable.
cost tracking
every agent run tracks tokens in, tokens out, and cost in USD. cost is calculated at the model's live rate and written to the database on gate approval.
you'll see per-agent cost on each agent card in the roster. total cost across the workflow appears in the outcome cards on the deck.
costs are displayed to four decimal places — $0.0012, not $0.00. you're running infrastructure. precision matters.
next