Run MARS from install to daily operations.

Install From Source

1. Clone the repository

   git clone https://github.com/greaveselliott/MARS.git
   cd MARS

2. Install the command

   make install
   mars version

   make install installs the current checkout and runs shell PATH setup through the installed binary.

3. Prepare local inference

   mars setup
   mars doctor

   Ordinary setup requires no GitHub credential; authenticated release access remains optional.

Bootstrap Your First Target Repository

1. Choose a separate git checkout

   The target project is the repo MARS will manage. Do not point ordinary autonomous runs at the MARS source repo.

2. Initialize the deployed harness

   mars init --repo ~/my-project

   This writes .harness/, AGENTS.md, goals, feature contracts, tickets, plans, release files, and guidance docs.

3. Review generated ownership

   After init, role prompts, manifests, guardrails, knowledge routes, tickets, and docs are target-owned. Edit them deliberately.

4. Run a health check

   mars doctor --repo ~/my-project --json

Inspect Before You Let Agents Mutate

mars run engineer --repo ~/my-project --dry-run

mars run engineer --repo ~/legacy-project --dry-run --no-init

mars tools list --json
mars mcp serve --repo ~/my-project --trust observer

Run Agents And The Autonomous Loop

mars run engineer --repo ~/my-project --execution-profile host --acknowledge-host-execution
mars run qa --repo ~/my-project --debug --execution-profile host --acknowledge-host-execution

mars start --repo ~/my-project --execution-profile host --acknowledge-host-execution

mars register --repo ~/my-project --remote owner/repo
mars serve --addr 127.0.0.1:9091 --concurrency 2 --execution-profile host --acknowledge-host-execution

run, start, serve, tools run, and mcp serve default to observer, which independently caps trust and blocks every mutator. Host has current-user authority and is not containment; isolated is unavailable.

Control Keys

Review And Accept Agent Work

After mars run, mars start, or mars serve has touched a target repo, treat the result like a developer handoff. MARS can prepare changes and evidence, but you decide what is accepted into the target history.

1. Stop new work while you review

   # In the running MARS terminal
   p
   
   # Or through the authenticated local dashboard
   # Log in, then choose Pause.

   Paused workers finish any running job, then claim no new jobs. Use this before reviewing a busy repo.

2. Check MARS health and the target state

   mars doctor --repo ~/my-project --json
   git -C ~/my-project status --short --branch
   git -C ~/my-project diff --stat

   Start with the health report and the git diff. If either looks surprising, investigate before running more agents.

3. Read the evidence, not just the summary

   git -C ~/my-project diff
   find ~/my-project/docs/tickets -maxdepth 2 -type f | sort
   find ~/my-project/docs/features -maxdepth 1 -type f | sort

   Check the code, tickets, feature contracts, plans, docs, traces, and dashboard state that support the claim.

4. Run the target checks

   mars checks run --repo ~/my-project --name test -- go test ./...
   mars scores export --repo ~/my-project --window-days 30

   Use the target's real build, test, lint, or smoke command. Refresh the quality score only when the recorded evidence supports it.

5. Choose the outcome

   Outcome	What to do	When to use it
   Accept	Commit the target-owned code, docs, and evidence together.	The diff matches the request and checks pass.
   Repair	Create or update a bounded ticket with the failing evidence, then run the right role again.	The direction is useful but incomplete or failing.
   Reject	Discard only the output you have reviewed and chosen not to keep.	The work is off-goal, unsafe, or not worth repairing.

6. Version accepted target changes

   mars release notes --repo ~/my-project --bump auto
   mars release backfill-notes --repo ~/my-project --check
   git -C ~/my-project status --short

   Generate release notes after accepted semantic changes, not after a rejected experiment.

Record Local Check Evidence

Use mars checks run when a build, test, lint, smoke, or release gate should become MARS evidence instead of terminal scrollback. The command runs inside the target repo, streams the check output to your terminal, and records a scoring outcome in the repo database so MARS can use it in quality reports and repair routing.

mars checks run --repo ~/my-project --name go-test -- go test ./...
mars scores export --repo ~/my-project --window-days 30

mars checks run \
  --repo ~/my-project \
  --role qa \
  --name browser-smoke \
  -- npm test

mars checks run --repo ~/my-project --name go-test -- go test ./...

For full semantics, DB behavior, failure routing, and inspection options, open the Local Checks Evidence Guide. For command flags, see CLI operations. For quality interpretation, see evidence workflow, quality score export, and checks and validation boundaries.

Operate The Dashboard

The dashboard is local and embedded in the Go binary today. Use it to observe role state, quality, queue flow, throughput, telemetry, and evolution history. Use --debug when you want inline trace/log streaming instead of the TTY dashboard. Use the Dashboard API Reference when scripting dashboard controls or building a companion UI.

Choose Local, Cloud, Or Deferred Model Routing

mars setup --inference local --local-bundle auto

mars init --repo ~/my-project --model-routing cloud --cloud-provider openai --cloud-model gpt-4.1-mini --api-key-env OPENAI_API_KEY --yes

mars models override --repo ~/my-project --tier coding --provider ollama --model qwen3.6:27b

mars models evaluate --provider ollama --model qwen3.6:27b

Update Installed And Deployed Surfaces

1. Check drift

   mars update check --repo ~/my-project --json

2. Update the installed command if needed

   mars auth github check
   mars update tool

   Use the Authentication And Credentials Reference when release auth or provider credentials are unclear.

3. Update target harness defaults if needed

   mars update harness --repo ~/my-project

   Updates fill missing defaults while preserving user-owned target config.

Release Workflows

mars release notes --repo . --bump auto
mars release backfill-notes --repo . --check
git commit -m "release: notes X.Y.Z"

Remove MARS From A Target Repo

1. Preview removal

   mars eject --repo ~/my-project

2. Apply only after reviewing the preview

   mars eject --repo ~/my-project --apply --confirm my-project

3. Choose database behavior

   Use --keep-db to leave the associated database in place. Use --delete-shared-db only when deliberately deleting the legacy shared DB.

Troubleshooting Decision Table