git:20260916.32e14cf to git:20260916.3e12c6f

57 added, 217 removed. Audit A to A.

---

name: aikito

description: Install, configure, and operate Aikito workspaces, including memory, skills, project resources, MCP servers, subagents, adoption, synchronization, and status verification.

---

# Aikito

## Purpose

- Use Aikito as the canonical, Git-managed source for durable Agent resources and

- synchronize those resources into supported coding agents and projects.

- Aikito governs resource ownership, scope, synchronization, and structural

- integrity. Ordinary file edits can be performed directly by Agents.

- The primary onboarding case is an existing Agent setup that has become tedious

- to maintain across tools, projects, or machines; adopt it before synchronization.

+ Use Aikito as the canonical, Git-managed source for Agent resources shared

+ across tools, projects, and machines. Existing Agent setups normally enter the

+ workspace through adoption; newly created resources start in the workspace.

- ## Mental Model

+ ## Core Model

- Keep the CLI source checkout (`~/aikito-src`) separate from the canonical user

- workspace (`<workspace>`, defaults to `~/aikito`). The workspace holds every

- source of truth:

+ Keep the CLI installation separate from the canonical user workspace

+ (`<workspace>`, normally `~/aikito`). When developing Aikito itself, keep its

+ source checkout separate from the workspace too:

```text

<workspace>/

- ├── agents.toml # detected Agents; Agent source of truth for all projects

- ├── skills.toml # global skill selection

- ├── skills/<skill-name>/

- ├── subagents.toml + subagents/

- ├── mcps/<name>.toml # file-based self-registration, no central registry

+ ├── agents.toml + skills.toml + subagents.toml

├── global/AGENTS.md

- ├── memory/ # global memory

- └── projects/<name>/ # agent.toml, AGENTS.md, memory/

+ ├── skills/ + subagents/ + mcps/

+ ├── memory/

+ └── projects/<name>/

```

Agent configuration directories and project `.agents/` directories are runtime

- entry points, never independent sources: modify canonical files first, then

- synchronize, and never edit or treat a generated Agent-native instruction, skill,

- subagent, or MCP entry as a source.

- New canonical resources follow `add → edit → show → sync → status / diff /

- doctor`; existing external resources enter through `adopt` and then rejoin that

- path at `show`. Run bare `aikito sync [--dry-run]` to orchestrate the entire

- workspace (global resources, host-gated subagents, tolerant MCP configs, and

- active projects).

- Resolve `<workspace>` with `aikito path workspace` before touching canonical

- files directly; `AIKITO_DIR` temporarily overrides the persisted workspace. Use

- the installed `aikito` command rather than assuming the CLI lives inside the

- workspace. Treat `aikito <command> --help` as the authority for options in the

- installed version, and when working from a source checkout consult its README

- and linked documentation for the current architecture and safety model.

+ targets, not independent sources. Modify canonical resources first and then

+ synchronize them. Never treat generated Agent-native instructions, skills,

+ subagents, or MCP entries as sources.

- ## Bootstrap

+ Resolve `<workspace>` with `aikito path workspace` before editing canonical

+ files directly. `AIKITO_DIR` temporarily overrides the persisted workspace.

+ Use the installed `aikito` command and treat `aikito <command> --help` as the

+ authority for the installed version's options.

- When the CLI is not installed, clone the official source outside the future

- workspace, after verifying the target holds no unrelated user data and without

- overwriting an existing checkout unprompted:

+ ## Choose a Workflow

- ```bash

- git clone https://github.com/lsaint/aikito.git "$HOME/aikito-src"

- export PATH="$HOME/aikito-src/bin:$PATH"

- ```

+ Read [references/installation.md](references/installation.md) when the CLI is

+ not installed or the user asks to install or upgrade Aikito.

- For an existing local Agent setup:

+ Bring an existing local Agent setup under management:

```bash

aikito init workspace ~/aikito

aikito adopt

aikito sync

aikito status

```

- When no supported external resources exist, skip `aikito adopt`; creating

- resources from scratch is a secondary path after workspace initialization.

- For an existing workspace on a new machine:

- ```bash

- # Download or clone your workspace repo to ~/aikito

- aikito init workspace ~/aikito

- aikito sync

- ```

+ Skip `adopt` when there are no supported external resources. On another

+ machine, clone or download the existing workspace, bind it with

+ `aikito init workspace <path>`, and run `aikito sync`.

- `aikito init workspace` refuses the CLI source tree, another source checkout,

- and an unrecognized non-empty directory. On an existing workspace, it binds the

- local pointer without modifying runtime configs. Uninstalled Agents and

- candidate paths on other machines are treated as `offline on this host` without

- failures.

+ New resources follow `add → edit → show → sync → status / diff / doctor`.

+ Existing resources follow `adopt → show → sync → status`. Bare `aikito sync`

+ orchestrates the entire workspace.

- ## Safety Protocol

+ ## Core Rules

- - Start read-only: inspect the relevant canonical files and run `aikito status`

- or the narrowest resource-specific status command. Do the same after every

- write, inspecting the reported targets.

- - Preview before applying when review is requested: use `--dry-run` for adoption

- and synchronization. Both commands preflight complete plans before their

- default write behavior. Show the user conflicts and credential handling first.

- - Treat unmanaged targets, drifted copies, and conflicting instructions as

- user decisions. Never silently overwrite them, and never force or prune

- merely to make status green. Warn first, scope the operation to the reviewed

- target, and review orphaned managed files before `--prune`.

- - Preserve unrelated user changes in both the workspace and target Agent

- configuration.

- - Keep API keys, tokens, passwords, and OAuth material out of the workspace and

- Git; store environment-variable references in canonical MCP configuration and

- never print, persist, or commit captured credentials.

- - A local Git repository is not safe to publish. Review memory and configuration

- for private data before adding a remote or pushing.

+ - Inspect relevant canonical files and current status before changing anything;

+ run `aikito status` or the narrowest resource-specific check afterward.

+ - Use `--dry-run` when the user requests a preview. Adoption and synchronization

+ already preflight their complete plans before writing by default.

+ - Never silently replace unmanaged targets, drifted copies, or conflicting

+ instructions. Do not use `--force` or `--prune` merely to make status green.

+ - Preserve unrelated changes in both the workspace and runtime targets.

+ - Keep credentials out of the workspace and Git. Canonical MCP definitions

+ should reference environment variables; never print or persist their values.

+ - Before publishing a workspace repository, review memory and configuration for

+ private data. A local Git repository is not automatically safe to publish.

## Resource Routing

- ### Global Instructions and Skills

- ```bash

- aikito add skill <name> [--description <desc>]

- aikito show skills | aikito show skill <target>

- aikito sync global --dry-run

- aikito sync global

- ```

- Adding, renaming, or removing a global skill is a cross-runtime migration, not a

- directory-only edit:

- - Update `skills.toml` and every reference to the old name. If the skill is a

- bundled CLI resource, update its source and init template in the CLI source

- checkout separately; the user workspace is never a release source.

- - Verify that each supported Agent loading global skills has the correct

- `skills_path` in `agents.toml` and in the `aikito init` template. An Agent CLI

- and its IDE may use different global skill directories.

- - Run the relevant tests, then `aikito sync global` and `aikito status`.

- - Inspect each managed Agent target: the new skill is visible and any stale link

- for the old name is gone.

- - Keep a global skill out of project `agent.toml` unless the project

- intentionally overrides or copies it.

- ### Projects

- A workspace normally exists once; a project registration represents one code

- directory and its project-specific resources. When a requested instruction,

- skill selection, or memory is project-specific and the current code directory is

- unregistered, ask whether to register it. Never register a project for a global

- resource.

- ```bash

- aikito init project [<name> <path>] # defaults to directory name and cwd

- aikito show projects | aikito show project <name>

- aikito sync project <name> [--dry-run|--force]

- aikito status | aikito diff

- ```

- `init project` creates the canonical skeleton

- (`projects/<name>/agent.toml`, `AGENTS.md`, `memory/`) and synchronizes its

- `.agents/` runtime. Existing unmanaged runtime resources, or a project name

- bound to another path, are conflicts for the user. Projects support candidate

- paths (`[paths]` table or `paths` array); non-existent paths on the host are

- marked `offline on this host` and skipped cleanly during sync.

- Project instructions and memory stay linked to canonical sources. Project skills

- follow `sync_mode`: `link` keeps symbolic links; `copy` generates managed copies

- for project Git tracking. `aikito status` detects copied-skill drift and

- `aikito diff` compares it with the canonical skill; synchronization refuses to

- replace drifted copies, so merge changes that should survive before using

- `--force`.

- Project instructions are linked for every Agent in the root `agents.toml` using

- each configured `project_instruction_path`. Shared targets are deduplicated, an

- existing unmanaged file or link is always a conflict, and an empty canonical

- project `AGENTS.md` disables these links. Synchronization cleans only links

- proven to target that canonical file, while `show project` reports a

- repository-owned `AGENTS.md` as an informational notice.

- `.agents/skills/` uses entry-level ownership: preserve project-owned skills not

- selected in `agent.toml` and report them only as notices, while a selected skill

- with the same name remains a conflict. Matching directory contents never prove

- Aikito ownership. `.agents/memory/` is exclusively Aikito-managed, so unknown

- entries there remain conflicts.

- The public Python `Project.prepare()` API is the execution-facing entry for an

- external runner. It requires exactly one active path (or an explicit `path`

- override), applies the same persistent project sync rules, and returns the

- resolved working directory. V1 supports Pi and never synchronizes global

- resources, MCP servers, or subagents as part of preparation. An explicit path

- may be an existing unregistered directory for an ephemeral CI or deployment

- checkout; the caller is responsible for selecting the correct path.

- ### MCP Servers

- Creating `mcps/<name>.toml` registers the server automatically.

- ```bash

- aikito add mcp <name> [--url <url> | --command <command>]

- aikito sync mcp --dry-run

- aikito sync mcp

- aikito show mcp [--live]

- aikito auth mcp <agent> <server>

- ```

- Use `--live` only when live Agent checks are useful. Missing credential

- environment variables emit a warning and skip the server gracefully without

- blocking synchronization of other MCP configurations.

- ### Subagents

- ```bash

- aikito add subagent <name> [--description <desc>]

- aikito sync subagents [--dry-run|--prune]

- aikito show subagents [--agent <agent>]

- aikito show subagent <target> [--agent]

- ```

- Subagent synchronization automatically host-gates against locally installed

- agents; `--prune` skips offline agents to protect definitions across hosts.

- ### Memory

- Global memory lives in `<workspace>/memory/`, project memory in

- `<workspace>/projects/<name>/memory/`.

- ```bash

- aikito show memory [target]

- aikito edit memory <target>

- aikito rename memory <target> <new-name>

- aikito rm memory <target>

- aikito doctor --fix

- ```

- Use the separate `durable-memory` skill to decide when knowledge is durable

- enough to persist, which scope owns it, and how to version it.

- ### Inbox

- Staging notes for review:

+ Use `aikito <command> --help` for exact arguments.

- ```bash

- aikito show inbox [target]

- aikito edit inbox <target>

- aikito rm inbox <target>

- ```

+ - Global instructions and skills: `aikito add skill`, `aikito show skill`, and

+ `aikito sync global`.

+ - Projects: `aikito init project`, `aikito show project`,

+ `aikito sync project`, `aikito status`, and `aikito diff`.

+ - MCP servers: `aikito add mcp`, `aikito show mcp`, `aikito sync mcp`, and

+ `aikito auth mcp`.

+ - Subagents: `aikito add subagent`, `aikito show subagent`, and

+ `aikito sync subagents`.

+ - Memory: `aikito show|edit|rename|rm memory`; use the `durable-memory` skill to

+ decide scope, content, and versioning.

+ - Inbox notes: `aikito show|edit|rm inbox`.

- ## Adoption

+ Read [references/projects.md](references/projects.md) when registering or

+ synchronizing projects, choosing `sync_mode`, handling multi-machine paths, or

+ using the public project API.

- `aikito adopt` preflights existing Agent configuration and imports it only when

- the complete plan has no instruction conflicts or invalid generated resources.

- Unreadable or malformed source configuration also blocks adoption. Use

- `aikito adopt --dry-run --verbose` for detailed read-only review. Application

- creates timestamped backups under

- `~/.aikito/backups/adopt_<timestamp>`. Adoption writes into the workspace only;

- Agent-native configuration changes during explicit synchronization. An

- instruction conflict blocks the entire apply operation. `aikito doctor` reports

- the same structured adoption findings but never imports or skips resources,

- including with `--fix`. If a resource is intentionally excluded, repeat

- `--skip instructions`, `--skip mcp/<name>`, or `--skip subagent/<name>` as

- needed. Skips are visible and last for one invocation; never use them to bypass

- an unreadable or malformed source. After adoption succeeds, run `aikito sync`;

- it preflights the complete workspace and writes only when the plan is safe. Use

- `aikito sync --dry-run --verbose` for a detailed read-only plan.

+ Read [references/adoption.md](references/adoption.md) when importing an existing

+ Agent setup or resolving adoption diagnostics.