The handoff is never stale.
The snapshot regenerates on every state change: task, decision, milestone, phase advance. Continuity is an engine guarantee, not a habit you have to keep.
Agents forget.Projects shouldn't.
Every new session starts by re-deriving what the last one already knew. AI-POS keeps the project's state in human-readable files an agent can take over from — and the engine, not the agent, decides whether the work actually passed.
Desktop app. Runs on your machine, against your folders. Execution stays with whichever agent you already use.
The engine marks the sheet
Exit gates are evaluated against real state. Nothing here is self-reported.
drawn by the enginewritten by a human
min_tasks(1)7/1passedno_blocked_tasks0 blockedpassedmin_decisions(1)3/1passed
artifact_exists(artifacts/release-notes.md)missingheldmanual_confirm("All tests pass and the main flows work in a real run")pending (human only)held
manual_confirm is the inverse of the others: only a person can satisfy it, and no tool exists for an agent to do so. Forcing any gate demands a reason and is written to an append-only ledger.
32
tools the hub — the local MCP server bundled with the app — exposes to an agent (13 read-only, 19 write)
12 of 16
write tools granted on day one in a new workspace — the remaining 4 stay behind a guard until a human allows them
6
capability groups write access is granted by — a human ticks a group, not 19 boxes
4
reasons a tool ships guarded: self-verification, gate bypass, cross-workspace writes, asset rewrites
specimen
There is no database. This is the whole product.
A workspace is a folder you chose. Every piece of state is a file you can open, diff, and commit. Snapshots and indexes are rebuildable derivatives; the ledger is append-only and is the audit record.
Which means the failure mode of most tools cannot happen here: if AI-POS vanished tomorrow, your project would still be readable.
Full disk contract →my-project/
AGENTS.md entry point + engine-maintained state block
project.yaml phase / progress / updated, synced line by line
aipos_docs/ operating guide for a headless session
memory/ cross-session memory, one fact per file
.mcp.json hub connection for the agent host
.aipos/
context.json goals, boundaries, metadata
workflow.json phases, AI instructions, exit gates, position
agent_access.json per-tool authorisation
ledger.jsonl append-only event ledger
snapshots/
latest_handoff.md
specs/ what the system does now (specs module only)
tasks/ one JSON per atomic task
artifacts/ deliverables<!-- AIPOS:STATE:BEGIN -->
> ⚙️ Maintained automatically by the AI-POS engine (hand edits are
overwritten on the next update); updated 2026-07-29T09:52:38Z
**Status**: Demo project (domain: coding) — 2 tasks: 1 todo /
1 in progress / 0 blocked / 0 done; current phase **Spec**
(1/5, template Software Development).
**Instructions for this phase**:
- Read the handoff and context.json, then shape the requirements
into a verifiable spec.
- Break the implementation into atomic tasks (with acceptance
criteria) under tasks/.
- Record key technical choices (framework, data structures,
boundaries) as decisions.
**Exit gates** (evaluated by the engine against real state):
- [x] min_tasks(1) — 2/1
- [x] min_decisions(1) — 1/1
**Next steps** (up to 5; ▶ = in progress):
- ▶ [P0] T-0001 — Design the data model
- · [P2] T-0002 — Write the user documentation
**Blockers**: none right now.
**Recent decisions**:
- `2026-07-29T09:52:38Z` Files are the source of truth; the
index can always be rebuilt
> Full content (recent ledger, all tasks, decisions in full) ->
[.aipos/snapshots/latest_handoff.md](.aipos/snapshots/latest_handoff.md)
<!-- AIPOS:STATE:END -->specimen
The block your agent reads first
The entry point is AGENTS.md — the filename any agent host reads; Claude Code gets there through a one-line CLAUDE.md shell. The engine rewrites the fenced block on every state change: task, decision, milestone, phase advance. Anything you hand-write outside the fence is never touched.
Delete the markers and the engine stops touching the file entirely. Continuity is a guarantee you can revoke.
Connect an agent →schematic
How those files got there
The folder and the AGENTS.md block above are what one agent call leaves behind. The agent asks; one gate decides what it may change; whatever it does change lands as a file you can open.
The full write path →
The loop
Break down
Split the phase into atomic tasks, each small enough to finish in one session.
Do the work
Yourself, or hand it to an agent. Statuses update as you go; blocked needs a reason.
Record decisions
The reasoning lands in the ledger, so no future session has to re-derive it.
Pass the gate
The engine checks real state. Forcing it demands a reason and is recorded as an override.
Hand off
The snapshot already regenerated. The next session reads it and picks up the thread.
What the structure buys you
Claimed done is not done.
Marking a task complete only records a claim. Verification is a separate mark that wants evidence attached, and "archive verified done" deliberately leaves unverified work on the list where you can see it.
The agent's reach is an allowlist.
One master switch decides whether agents reach the hub at all. With it on, read-only tools need no further setup; writes are authorised per tool. Self-verification, phase advances, publishing a delivery, and rewriting workspace assets stay off until you open them. Every call, including denied ones, lands in the ledger.
Parallel agents can't jump the queue.
With the collaboration module on, give tasks an assignee and prerequisites and the engine blocks starting or finishing out of order. Claims cannot be stolen. "Don't start what isn't unblocked" stops being a discipline and becomes a refusal.
Projects can feed each other.
With the team module on, wire workspaces into a directed graph and one project delivers to another's inbox, with attachments. Agents can publish but never route: a delivery moves because you pressed send, or because you switched on auto-send for that line in advance. Inbox content is defined as data, not instructions.
Ships with five workflows
generic-v1Generic Workflowany projectcoding-v1Software Developmentwriting coderesearch-v1Researchliterature and reportsbusiness-v1Business Planningbusiness planninglife-v1Life Planningpersonal goals
Templates are data. Drop a JSON file into ~/.aipos/templates/ to add your own or shadow a built-in, with no recompilation.
Runs the agent CLIs you already use
The built-in terminal runs Claude Code, Codex CLI, Gemini CLI, or a plain shell in the workspace root. Sessions belong to the app, so switching projects doesn't interrupt them, and a running terminal can pop out into its own window.
The Claude CLI picks up .mcp.json and connects to the hub automatically; other vendors' CLIs wire up MCP differently and do not. Custom entries can carry environment variables, which is how you point one at a local model.
Get it
Installers for Windows, macOS and Linux are on the latest release — including a portable Windows build that needs no installer. They are unsigned pre-release builds and do not update themselves. Building from source stays supported:
The hub server agents connect through is bundled either way, so you never compile it or set PATH by hand. AI-POS points each workspace's .mcp.json at it, and the Tools page repairs that pointer in one press if it goes stale.
git clone https://github.com/white1024/ai-pos.git
cd ai-pos
pnpm install
pnpm tauri build
# the installer lands in target/release/bundle/ — run itStart with one folder.
Initialise a project, break the first phase into tasks, and let the engine hold the thread while you and your agent do the work.
Builds are unsigned, so Windows and macOS warn about an unknown publisher on first launch, and nothing updates itself. The docs say exactly which dialog you will see and how to get past it.