aikito git:20260916.3e12c6fA

Immutable. This exact content never changes and is served at /api/v1/blob/c7a0ef848c8e0250.

---
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 Agent resources shared
across tools, projects, and machines. Existing Agent setups normally enter the
workspace through adoption; newly created resources start in the workspace.

## Core Model

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 + skills.toml + subagents.toml
├── global/AGENTS.md
├── skills/ + subagents/ + mcps/
├── memory/
└── projects/<name>/
```

Agent configuration directories and project `.agents/` directories are runtime
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.

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.

## Choose a Workflow

Read [references/installation.md](references/installation.md) when the CLI is
not installed or the user asks to install or upgrade Aikito.

Bring an existing local Agent setup under management:

```bash
aikito init workspace ~/aikito
aikito adopt
aikito sync
aikito status
```

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`.

New resources follow `add → edit → show → sync → status / diff / doctor`.
Existing resources follow `adopt → show → sync → status`. Bare `aikito sync`
orchestrates the entire workspace.

## Core Rules

- 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

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

- 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`.

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.

Read [references/adoption.md](references/adoption.md) when importing an existing
Agent setup or resolving adoption diagnostics.