Aiko - Local AI Development Orchestrator

🌐 English - Русский

Aiko (AI kanban orchestrator) is a local-first orchestrator for AI-assisted development: one loopback daemon that gives Claude Code, Codex, Cursor, ZCode, Cline and OpenCode a shared project context, a configurable Kanban pipeline, durable memory and a stable MCP contract - while you keep every file on disk, in Git-friendly Markdown and JSON.

Aiko does not replace your agents. It connects them: cards move through user-defined workflow stages, each stage can run in a different agent, and an unfinished stage (for example, after a rate limit) hands off to another agent without losing history.

File-first storage - one typed card graph - effective priorities - agent handoffs with full attempt history - durable project memory - loopback-only by design

---

Screenshots

Captured from the Aiko project: dashboard and board at commit 20d2e19; project overview, card and project settings at 51e8340. These development builds use the English interface and light Studio Modern palette. Project paths are anonymized; card titles retain their original language. Click an image to open it at full size.

Dashboard — projects, current work and activity across the workspace.

Kanban board — the Aiko task pipeline, active runs and cards across stages.

Project overview — activity, pipeline velocity, card distribution and cumulative flow.

Card page — requirements, declared scope, execution status and scoring for a real Aiko task.

Project settings — workspace policies, priority formula and scoring criteria.

---

Features

• Local daemon, one per user - a single ASP.NET Core process serves every registered project: REST API, project-scoped MCP over Streamable HTTP, health endpoints and the PWA
• Kanban PWA on Blazor WebAssembly (Flare.Blazor) with a board that draws every card type as its own section and filters by type in place, a backlog screen, the card editor, artifacts and executions; the interface language follows the browser, English and Russian ship, and any other language falls back to English
• Card types you define yourself - a card type is a workflow: add a Bug with its own description, icon and colour right in the workflow editor, and it appears in the pickers, as a board section and in the backlog; every status column carries its own icon and colour too. The backlog column is standard and cannot be removed, and a dedicated Backlog screen gathers every card that has not been taken into work yet
• A default template that is already worked out - a new project starts from epic, story and task pipelines in which every status carries an icon, a colour and an instruction saying what the agent does there, the card types come with their descriptions, and cards are scored by three criteria - app-point, user-point and complete - whose readiness score the agent re-calculates after every change
• Cards as folders - every card is a directory with a card.json (optimistic revisions) and Markdown artifacts; the whole .aiko tree is readable, diffable and Git-friendly
• Readable project addresses - a project gets a short id derived from its folder name (Cyrillic is transliterated), editable while it is created and used in every URL (/p/aiko/board); the generated GUID stays as the immutable key inside card files and agent endpoints, so cross-project links never break
• Typed card graph - implements, parent-child, blocks (cycle-checked) and symmetric relates-to relations; blocks drive scheduling
• Effective priorities - each card has its own score; task priorities blend in the maximum parent value with configurable weights (versioned formula)
• Execution loop - StageExecution owns the workspace; AgentAttempt records each agent's run, so handoff, resume, pause and rate-limit states never lose history
• Durable memory - decisions, conventions and lessons live in .aiko/memory as Markdown and are searchable through an SQLite FTS5 index
• Unified agent installer - discovers Claude Code, Codex, Cursor, ZCode, Cline and OpenCode installations and applies idempotent, user-config-preserving project configuration (MCP entries, managed blocks, owned skills/commands) with per-adapter plans and surgical uninstall
• .aiko is the source of truth - cards, workflows, artifacts and memory live in .aiko files; the global SQLite database holds the project registry, the run history, the event journal and the search indexes. reindex rebuilds the indexes from .aiko, but the run history and the journal exist only in the database, so keep it
• Security by default - loopback bind only, Host/Origin validation against DNS rebinding and any origin but the daemon's own page, bearer-only MCP, no framing, no wildcard CORS
• Git, read through your own client - the branch, the changes, the log and the diff of a card's files, read by running the git executable; a machine without it says "Git client unavailable" instead of failing. Aiko only reads the repository - the one file it edits is .gitignore, when a project is registered under the local-only git policy - and never commits: commits are the agent's, under the project's commit policy
• Workflow sets you can author - the pipelines and defaults a project starts from, plus what an agent must do right after creating it (the structure the project should have, for instance): captured from a project, exported and imported between machines, and applied to an existing project by an explicit action
• Screens that answer questions - a project page (cards per stage, weekly velocity, triage distribution, re-index), a card page (scope, acceptance criteria, live diff, discussion, runs) and a daemon page (uptime, runs and crashes, memory, agent bridges)

---

Install

Windows 10/11, x64. The release is self-contained, so neither the .NET SDK nor the .NET runtime is required:

irm https://raw.githubusercontent.com/jrfrigat/Aiko/main/scripts/install.ps1 | iex

The installer downloads the newest aiko-<version>-win-x64.zip, unpacks it into %LOCALAPPDATA%\Aiko\bin (CLI aiko, stdio proxy aiko-stdio, the daemon in server\) and adds that directory to the user PATH. Nothing is installed machine-wide and no administrator rights are needed.

At the end it connects the agents it finds on this machine (aiko agent install --scope user): the global /aiko-* skills, commands and rules go into those and nobody else (each project connects its agents to its own MCP endpoint with aiko agent install --project <id>). Name them instead with -Agents claude-code,codex, or skip the step with -NoAgentSetup.

aiko serve     # start the daemon in this terminal (loopback only; prefers port 24560)
aiko serve -d  # the same, in the background: it survives closing this terminal
aiko serve stop                    # stop the daemon again, from any terminal
aiko ui        # pair the browser with the daemon and open the board (starts one if none runs)
aiko doctor    # check the installation; `aiko repair --fix` applies the fixes it names

Pin a specific release or choose another directory by fetching the script into a scriptblock first:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/jrfrigat/Aiko/main/scripts/install.ps1))) `
    -Version v0.3.1 -InstallDir D:\Tools\Aiko

Re-running the installer is the update path: binaries are replaced, project data and settings are kept. To remove Aiko, run aiko uninstall: it stops the daemon, removes autostart and the installed binaries, and takes %LOCALAPPDATA%\Aiko\bin off the user PATH. .aiko directories and the database are never deleted automatically.

Configuration

Environment variable	Purpose
AIKO_PORT	Explicit port for this launch; validated and persisted
AIKO_URL	Explicit loopback origin (overrides port selection)
AIKO_DATABASE	Path to the SQLite database (default %LocalAppData%/Aiko/aiko.db)
AIKO_LOG_FILE	File a background daemon logs to (set by aiko serve -d; default <data>/daemon.log)

Tests

dotnet test Aiko.slnx

113 xUnit facts across four suites: domain rules, infrastructure/file/SQLite behavior, daemon integration (MCP tools plus the REST API, its status codes and the loopback/Host/Origin guard) and the client JSON contract. The integration suite boots its own daemon on a random port with an isolated database - no manual orchestration needed.

---

Run from source

Prerequisites: .NET 10 SDK.

git clone https://github.com/jrfrigat/Aiko
cd Aiko

# build everything (server, PWA, CLI, stdio proxy, tests)
dotnet build Aiko.slnx

# run the daemon (serves the PWA and the MCP endpoints)
dotnet run --project src/Aiko.Server

The daemon prefers port 24560; if it is busy it picks a free port from 18000-18999 and remembers the choice in settings.json next to the database. Open the UI at http://127.0.0.1:24560 and register a project through the interface, or from the terminal:

curl -X POST http://127.0.0.1:24560/api/v1/projects/initialize \
     -H "Authorization: Bearer $(aiko token)" \
     -H "Content-Type: application/json" \
     -d "{ \"rootPath\": \"C:/path/to/your/project\" }"
# => { "id": "<projectId>", ... }   MCP: http://127.0.0.1:24560/mcp/projects/<handle>

Every REST and MCP request carries the access token; aiko token prints it.

.\install.ps1 in the repository root publishes this checkout into %LOCALAPPDATA%\Aiko\bin, so aiko serve and aiko status behave exactly as in an installed release.

---

How agents connect

Each project gets a dedicated Streamable HTTP MCP endpoint:

http://127.0.0.1:<port>/mcp/projects/<handle>

<handle> is the project's readable slug - the same one the UI's URLs carry. The daemon resolves a project by its handle or by its id, so an endpoint written before slugs existed keeps working.

Clients without reliable Streamable HTTP use the thin stdio proxy (no second store, raw transport forwarding, loopback-only):

aiko-stdio --url http://127.0.0.1:<port>/mcp/projects/<handle>

The stable tool set (43 tools): project context, card CRUD, linking, estimating and taking a card, the card discussion (adding and reading the notes on a card), the full stage-execution life cycle (start / report progress / request scope expansion / complete / pause / handoff / resume / report agent state), memory search and store, project registration and listing, templates, diagnostics and reindex, settings, backup and opening the UI. Tool descriptions instruct agents to fetch the project context first; installed skills, rules and AGENTS.md blocks reinforce it per agent.

Skills and rules

Two channels, because a contract and a procedure are not the same thing. A skill is a procedure a model loads when it judges the description relevant; a rule is read on every run, which is what the working contract needs.

Project scope (--project <id>) installs every procedure as a skill, and as a slash command for the clients that have commands. One create procedure per card type the project defines is generated alongside them:

Skill / command	Does
aiko-create <type> <description>, aiko-create-<type>	Create a card of any type this project defines: Aiko names it, lands it in backlog and the agent estimates its size and scores
aiko-create-sub <parentCardId> <type> <description>	Create a sub-card under a card: the same creation, plus the parent-child link
aiko-estimate <cardId>	Estimate a card: the agent judges the size step and the criterion scores
aiko-run <cardId> [stageId]	Run a card: do what its current stage asks for, report progress and complete it; a stage id moves it there first
aiko-scope	Ask for a scope expansion
aiko-handoff	Hand the stage over to another agent
aiko-memory	Store and search project memory
aiko-status	Summarize what is in progress
aiko-ui	Open the board for this project

The working contract travels in the rule channel instead, one file per client: a marked block in CLAUDE.md (Claude Code), AGENTS.md (Codex, ZCode and OpenCode) and .clinerules/aiko.md (Cline), or the rule Aiko owns in .cursor/rules/aiko.mdc (Cursor).

User scope (--scope user), available without a project open. One skill explains the flow; the actions themselves are commands:

Command	Does
/aiko-init [name] [id]	Register the current directory as a project; the id is the readable handle its URLs use
/aiko-list-projects	List the registered projects
/aiko-status	Daemon health, data directory, port
/aiko-doctor	Diagnose the installation (changes nothing)
/aiko-repair	Apply the fixes the diagnosis named
/aiko-agents	List, install and uninstall the agents' integrations
/aiko-settings	Read and change settings - a project's own, or a template's defaults for new projects
/aiko-token	Show the local access token
/aiko-backup	Back up a project's .aiko tree
/aiko-logs	Tail of the daemon log, and a project's event journal with --project <id>
/aiko-update	Update the installed Aiko to a release, or report what is available
/aiko-ui	Open the UI

/aiko-update wraps the aiko update command that ships with this release: aiko update --check reports what is available without changing anything, and aiko update verifies the release's published checksum, replaces the installed binaries with it and reconnects this machine's agents to the new daemon. The data directory, the settings and the projects are not touched. Updating replaces the daemon that is running, so the moment is the person's to choose rather than something an agent applies because a version is available.

Agent Integration has the full skill → MCP tool → UI table, including what the UI cannot do yet.

---

Repository layout

Project	Responsibility
src/Aiko.Domain	Cards, relations, workflows, priorities, executions - no I/O, no agents
src/Aiko.Application	Use cases and ports (stores, coordinator, installer contracts)
src/Aiko.Infrastructure	File stores, SQLite projections, FTS5 memory, agent adapters
src/Aiko.Server	ASP.NET Core daemon: REST API, MCP endpoints, PWA hosting
src/Aiko.Pwa	Blazor WebAssembly PWA on Flare.Blazor
src/Aiko.StdioProxy	Short-lived stdio <-> Streamable HTTP MCP proxy
tests/*	xUnit suites: Domain.Specs, Infrastructure.Specs, Mcp.Specs (self-hosted), Pwa.Specs (JSON contract)
scripts/install.ps1	Release installer behind the one-line install command
.github/workflows/	ci.yml (build, test, lint the installers) and release.yml (win-x64 assets)

---

Documentation

• Installation - install, run, configure, update and uninstall
• Getting Started - first project in a few minutes
• User Guide - board, cards, workflows, git, discussion, analytics, executions, memory
• Agent Integration - MCP endpoints, tools, skills, installer output
• Troubleshooting - common problems and fixes
• Technical Specification - the normative MVP specification
• Requirements Discussion - the journal of decisions
• Original Terms of Reference - the historical source document
• Contributing - build, test and pull request expectations
• License - MIT

---

Status

Implemented and covered by the test suites: the daemon (REST, project-scoped and daemon-level MCP, SSE), file-first storage with rebuildable SQLite projections, the typed card graph with effective priorities, the execution loop (attempts, handoffs, pause/resume, commit policies), durable memory, the unified agent installer, and the PWA - board, project page, card page (scope, acceptance criteria, live diff, discussion, runs), workflow sets, agent bridges and analytics.

Post-MVP, as tracked in §29 of the specification: git push and branch handling, WorkspaceMode.Worktree, filesystem watching and reconciliation, agent autolaunch, the interactive installer, and the memory and journal screens in the UI.