Docs and field notes

Amistio guides

Browse the product manual, project-brain explainers, AI workflow articles, local runner setup, MCP/tooling notes, and troubleshooting references from one place.

Open the app Use template Browse guides

Library shape

Start hereSetup, template, project brain

Field notesAgents, harnesses, AI history, MCP

ReferenceCLI, sync, local runner, status

Start here

Pick the path that matches why you came.

The docs hub now behaves like a library: choose a setup path, a concept guide, or the open-source template path first.

StartSet up AmistioInstall the CLI, prepare a repository, pair it with the app, and keep the local runner online.ConceptUnderstand the brainSee how memory, ADRs, plans, prompts, workflows, AGENTS.md, context, and architecture fit together.TemplateUse the template firstStart open source today, keep the project brain in your repo, and import later if the hosted app fits.

Featured

The highest-signal guides first.

These are the pages most likely to answer what Amistio is, how the brain works, and how AI tooling fits the local-runner boundary.

The Amistio project brainFeaturedA visual guide to the repo-native brain files that turn wishes into reviewable work.Project memoryBrainHow lessons, conventions, warnings, and reusable patterns shape the next run.MCP and AmistioToolsWhat Model Context Protocol means for tool boundaries and future-safe agent integrations.What is an AI agent?LearningA practical explanation of agents, goals, tools, context, stop conditions, and review gates.

Collections

Docs, articles, and references by intent.

The page is no longer one long manual. It is organized around what a visitor is trying to understand or do.

Project brain

How Amistio remembers work

Deep dives for the files that make agent work inspectable: memory, ADRs, plans, prompts, workflows, context, and instructions.

Project brain mapOverviewThe full artifact map: AGENTS.md, architecture, context, ADRs, features, memory, plans, workflows, and prompts.MemoryBrain fileLessons and conventions that keep future agent work from repeating old mistakes.Decisions and ADRsBrain fileOptions, tradeoffs, consequences, and the decision gate before implementation.Plans and workflowsBrain fileSequenced work, acceptance checks, and repeatable operating procedures.Implementation promptsBrain fileModel-agnostic prompt files that become one reviewable work unit.AGENTS.mdRulesRepo instructions, agent operating rules, planning gates, and safety boundaries.

Learning

Blog-style guides and explainers

Readable background pieces for visitors learning the vocabulary around agents, harnesses, templates, and AI history.

Open-source templateTemplateStart with the Amistio project-brain template before adopting the hosted product.What is an agent?AI basicsAgent vocabulary for software teams: goals, tools, context, loops, and review.What is a harness?AI basicsHow harnesses control inputs, permissions, tools, verification, and local execution.A practical history of AIBackgroundA concise timeline from symbolic systems to modern foundation-model agents.

Tools

MCP, local tools, and sessions

Practical guidance for the tool layer around Amistio's local runner and project-brain workflow.

MCP and AmistioProtocolModel Context Protocol, tool discovery, controlled context, and Amistio's local-runner boundary.Local AI toolsRunnerSupported local tools, provider setup ownership, custom commands, and runner capability checks.Tool sessionsRunnerWhen to continue related context and when a fresh session is safer.

Operations

Setup, runner, and support

Reference material for pairing, sync, CLI commands, runner execution, status, and troubleshooting.

Setup pathReferenceThe shortest path from app project to paired repository and running local runner.CLI command referenceReferenceInstall, init, onboard, bootstrap, import, pair, sync, run, and runner service commands.Local runner executionReferenceWhat runs locally, what the app coordinates, and what runner status reports.TroubleshootingSupportCommon setup, pairing, runner, and local tool issues with next actions.System statusSupportCheck service health and origin behavior when app actions are not responding.PrivacyTrustHow the public policy frames account, project, runner, and local-tool boundaries.

Setup reference

From app project to paired local runner.

The setup content stays on this page, but it is compact now so the hub can support both docs and learning articles.

1Create or select a project in the app.

2Install `@amistio/cli` on the machine that owns repository work.

3Initialize, onboard, bootstrap, or import the repository.

4Pair the checkout with the web project.

5Choose and authenticate a local AI tool.

6Run the local runner so generated brain artifacts and approved work can be processed.

Pairing and sync

Link non-secret hosted repository metadata in the app, then pair or import from a local checkout. Approved brain records sync into `docs/` folders; local changes can be pushed back for review, and concurrent edits create visible conflicts.

Template guide Project brain map

CLI reference

Commands you need after choosing a path.

Keep this section nearby for setup, runner work, bounded retries, and local-tool execution limits.

npm install -g @amistio/cli

Install the stable Amistio CLI runner.

amistio --help

Confirm the runner command is available.

amistio tools

Check supported local AI tools detected on this machine.

amistio init

Create control-plane folders for a new project.

amistio onboard

Inspect or prepare an existing repository for Amistio.

amistio bootstrap --repo-url <cloneUrl> --target <path> --account <accountId> --project <projectId> --repository-link <repositoryLinkId> --pairing-code <code>

Clone, prepare, and pair a linked repository locally.

amistio import <code>

Pair an existing checkout and import accepted legacy Markdown/MDX docs.

amistio pair --account <accountId> --project <projectId> --pairing-code <code>

Pair a local checkout with a web project.

amistio sync status

Show brain file state, pending docs, dirty edits, and conflicts.

amistio sync pull

Materialize approved web brain artifacts into docs/ folders.

amistio sync push

Push local synced brain changes back to the app for review.

amistio run --watch

Claim queued brain-generation and approved implementation work.

amistio run --watch --max-preflight-attempts 3 --tool-timeout-seconds 1800

Use explicit bounded setup retry and local-tool timeout limits.

amistio run --watch --background

Start a detached background runner for the paired checkout.

amistio runner status

Check detached runner state, heartbeat, and bounded resource sample.

amistio runner stop

Stop the detached background runner.

amistio runner service install

Install a user-level startup service where available.

amistio runner service status

Show startup service state and descriptor location.

amistio runner service remove

Unload and remove the user-level startup service.

Local runner

Execution stays on your machine.

The web app coordinates wishes, generated brain artifacts, approvals, queues, heartbeats, status, and bounded runner resource samples.

Brain generation and approved implementation work run through the local `amistio` CLI runner from a paired repository with a local machine credential and a usable local AI tool. Runner lifecycle actions such as update, restart, and remove are limited to the paired runner owner or an organization admin. Git worktree preflight retries, local-tool timeouts, lease renewal, and status milestones are recorded as safe summaries. Source code, secrets, process lists, environment variables, command lines, credentials, and arbitrary local paths are not uploaded as public status data.

opencodeInstall and authenticate the opencode local runtime.Setup

ClaudeSet up Claude Code or Claude Agent SDK authentication locally.Setup

CodexSet up Codex CLI or SDK authentication locally.Setup

CopilotUse local GitHub Copilot authentication; the runner blocks mutating SDK permissions unless locally opted in.Setup

GeminiInstall and authenticate the Gemini CLI.Setup

AiderInstall Aider for local command execution.Setup

Cursor AgentInstall and authenticate the Cursor agent CLI.Setup

Troubleshooting

When the path gets stuck.

Use these checks when setup, pairing, local tools, sync, or runner claiming does not behave as expected.

The app cannot reach the server

Open the status page from the same origin and confirm the web app, server routes, and local port checks are healthy.

The repository is not paired

Create a pairing code, then run `amistio import <code>` from an existing checkout, or use bootstrap for first-time clone setup.

Bootstrap clone fails

Confirm local Git can clone the repository with your SSH key, credential helper, provider CLI, or keychain.

No supported local AI tool is installed

Install and authenticate one supported tool, then run `amistio tools` or refresh the runner panel.

No work is claimed

Confirm the repository link is active, the work item is approved, and `amistio run --watch` is running from the paired repository.

Git worktree setup keeps failing

The runner retries preflight setup up to `--max-preflight-attempts`, then fails the work item with the last safe error summary.

A brain file changed in two places

Resolve the conflict intentionally before syncing over either the web record or the repo copy.

Open status Terms