ai-pos

<div align="center"> <img src="src-tauri/icons/128x128.png" alt="" width="88" height="88" /> <h1>AI-POS</h1> <p><strong>Agents forget. Projects shouldn't.</strong></p> <p>A desktop app that turns any long-running project into human-readable files an AI agent can take over from — with phase gates the engine checks against real state, not against what anyone claims.</p> <p> <img src="https://img.shields.io/badge/Tauri%20v2-Rust%20%2B%20React-informational" alt="Tauri v2, Rust and React" /> <img src="https://img.shields.io/badge/status-pre--release-informational" alt="Pre-release" /> <img src="https://img.shields.io/badge/license-MIT-informational" alt="MIT licence" /> </p> </div> --- An AI session is short and forgetful; a real project is long and full of context. Most of the friction in working with agents comes from that mismatch — every new session starts by re-deriving what the last one already knew, and whatever never got written down is simply gone. AI-POS keeps that context in files the engine keeps fresh. You make the decisions, your agent does the work, and a handoff stays possible at every moment. > [!IMPORTANT] > Installers are on the [releases page](https://github.com/white1024/ai-pos/releases/latest), for Windows x64, Linux x64 and macOS arm64. They are unsigned pre-release builds — Windows and macOS warn about an unknown publisher on first launch — and nothing updates itself yet. Development is Windows-first. [Quick start](#quick-start) covers both downloading and building from source. ## What it organises Any body of work — software, research, a side business, life planning — into four things: - **Project** — a folder you chose. Every piece of state is a file you can open, diff, and commit. - **Tasks** — atomic units of work, each small enough to finish in one session, with a status and optional prerequisites. - **Phases and gates** — the project moves through phases from a template (the generic one runs plan → execute → review → retrospect), and each phase has **exit gates** the engine evaluates against real state. - **Handoff snapshot** — "where things stand and what comes next", regenerated by the engine on every state change. A new session, a new machine, or a different person reads one file and picks up the thread. > [!NOTE] > AI-POS is not an agent and has no cloud backend. It is the management hub; execution belongs to whichever agent you already use — Claude Code, Codex CLI, Gemini CLI, or you. ## Features - **Files are the whole product.** No database. Snapshots and search indexes are rebuildable derivatives; the ledger is append-only and is the audit record. If AI-POS vanished tomorrow, your project would still be readable. - **Gates you cannot mark yourself.** `min_tasks(n)`, `all_tasks_done`, `artifact_exists(path)` and the rest are computed from disk, never self-reported. `manual_confirm` is the inverse — only a human can satisfy it, and no tool exists for an agent to do so. Forcing any gate demands a reason and is written to the ledger. ([the full set](https://white1024.github.io/ai-pos/gates/)) - **A handoff that is never stale.** The snapshot regenerates on task, decision, milestone, and phase changes, so it is never older than your last action. - **Claimed done is not done.** Completing a task records a claim; verification is a separate mark that *requires* evidence, and the bulk archive sweep collects only verified work, deliberately leaving the rest on the list where you can see it. - **Agent 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, and writes are authorised per tool, with the gatekeeping ones off by default. Every call — including denied ones — lands in the ledger. - **Parallel agents can't jump the queue.** Give tasks an assignee and prerequisites and the engine refuses out-of-order starts and finishes. Claims cannot be stolen. - **A terminal that runs the real CLIs.** A genuine PTY process per agent CLI, rooted at the workspace. Sessions belong to the app, so switching projects doesn't interrupt them, and a running terminal can pop out into its own window. - **Projects can feed each other.** Wire workspaces into a directed graph and one project delivers to another's inbox, with attachments. An agent can publish but never route — routing is a human action, or a per-edge automation a human switches on. Inbox content is defined as data, not instructions. - **A spec layer that stays current.** `specs/<capability>/spec.md` records what the system does *now*; task bundles hold the deltas, and archiving a verified task folds its delta into the main spec. The folding is enforced; writing the delta is prompted by the agent's operating protocol. - **Search and portable backups.** Full-text search over the workspace (language-agnostic chunking into an SQLite FTS5 index), and export/import of the management layer — tasks, specs, ledger and handoff material — as a zip you can carry to another machine. Your own source files are not in it: they travel with the folder, or with git. > [!NOTE] > Collaboration (assignees and prerequisites), teams, and the spec layer are **capability modules**: you tick them on when you create the workspace, and a fresh project ships with none of them enabled. Everything above them in the list is always on. ## How it works A managed workspace is an ordinary folder. Abridged to the parts you will actually open: ``` 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/ workflow.json phases, AI instructions, exit gates, position agent_access.json per-tool authorisation ledger.jsonl append-only event ledger snapshots/latest_handoff.md tasks/ artifacts/ specs/ only when the specs module is on ``` The entry point is `AGENTS.md` — the filename agent hosts look for; Claude Code gets there through a one-line `CLAUDE.md` shell. The engine rewrites the fenced block on every state change and never touches anything you hand-write outside it: ```markdown <!-- 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 <!-- AIPOS:STATE:END --> ``` That block is real output, not a mock-up: `cargo run -p aipos-core --example gen_demo -- <dir> en` produces it. Delete the markers and the engine stops touching the file entirely. Continuity is a guarantee you can revoke. Both listings above are abridged. The authoritative account of what lands on disk, which files are the truth and which are rebuildable derivatives, is the [disk contract](https://white1024.github.io/ai-pos/reference/disk-contract/). ## Quick start **Download** an installer from the [latest release](https://github.com/white1024/ai-pos/releases/latest): | Platform | What to take | |---|---| | Windows x64 | `.msi` or `.exe` to install — or the `_portable.zip`, which needs no installer at all | | macOS arm64 | `.dmg` | | Linux x64 | `.deb`, `.AppImage`, or `.rpm` | Nothing is code-signed, so the first launch raises an unknown-publisher warning: SmartScreen on Windows, Gatekeeper on macOS. Nothing updates itself either — a newer version means coming back here for it. <details> <summary><strong>Or build from source</strong></summary> **Prerequisites** — Rust (stable, MSVC toolchain on Windows), [pnpm](https://pnpm.io/), and WebView2 on Windows 10. You don't need to manage Node: the repo pins the version and pnpm fetches it. ```bash git clone https://github.com/white1024/ai-pos.git cd ai-pos pnpm install pnpm tauri build # the first build takes a while ``` The installer lands under `target/release/bundle/`. If you are developing, `pnpm tauri dev` runs the app without installing. </details> Then: 1. **Create a project** — launch the app, choose *Initialize new project*, pick a folder, name it, pick a workflow template, and tick any capability modules you want (collaboration, teams, specs — all off unless you tick them). Templates ship built in for software, research, business, life planning, and anything else; drop a JSON file into `~/.aipos/templates/` to add your own, with no recompilation. 2. **Connect an agent** *(optional)* — authorise the write tools you want on the Tools page, then open your agent CLI in the project folder. > [!TIP] > You never build or locate the hub server yourself. It is compiled and bundled into the installer, and AI-POS points each workspace's `.mcp.json` at it; the Tools page repairs that pointer in one press if it ever goes stale. The Claude CLI picks `.mcp.json` up and connects automatically; other vendors' CLIs wire up MCP (the Model Context Protocol — the open standard agents use to call external tools) differently and do not, but the server itself is a plain stdio MCP server any client can spawn. Full walkthrough: [install](https://white1024.github.io/ai-pos/install/) → [first project](https://white1024.github.io/ai-pos/first-project/) → [connect an agent](https://white1024.github.io/ai-pos/agents/connect/). ## Documentation User-facing documentation is the **project website**, at **<https://white1024.github.io/ai-pos/>**. It is the source of truth — this README links to it rather than repeating it, and the pages below are the whole of it. | Topic | Document | |---|---| | What AI-POS is | [what-is-ai-pos](https://white1024.github.io/ai-pos/what-is-ai-pos/) | | Install · Your first project | [install](https://white1024.github.io/ai-pos/install/) · [first-project](https://white1024.github.io/ai-pos/first-project/) | | Tour of the app | [app-tour](https://white1024.github.io/ai-pos/app-tour/) | | Daily loop · Gates | [daily-loop](https://white1024.github.io/ai-pos/daily-loop/) · [gates](https://white1024.github.io/ai-pos/gates/) | | Connecting AI agents | [connect](https://white1024.github.io/ai-pos/agents/connect/) · [terminal](https://white1024.github.io/ai-pos/agents/terminal/) · [multi-agent](https://white1024.github.io/ai-pos/agents/multi-agent/) | | Teams · Backup · FAQ | [teams](https://white1024.github.io/ai-pos/teams/) · [backup](https://white1024.github.io/ai-pos/backup/) · [faq](https://white1024.github.io/ai-pos/faq/) | | **Architecture** | [reference/architecture](https://white1024.github.io/ai-pos/reference/architecture/) | | **Disk contract** (authoritative) | [reference/disk-contract](https://white1024.github.io/ai-pos/reference/disk-contract/) | | **Hub MCP tools** · **IPC commands** | [reference/mcp-tools](https://white1024.github.io/ai-pos/reference/mcp-tools/) · [reference/ipc-commands](https://white1024.github.io/ai-pos/reference/ipc-commands/) | | **Building and packaging** | [reference/building](https://white1024.github.io/ai-pos/reference/building/) | ## Architecture at a glance ``` React 19 + TypeScript UI | Tauri IPC src-tauri/ thin delivery layer crates/aipos-core/ domain core, zero Tauri dependencies crates/aipos-mcp/ hub MCP server (stdio), spawned by the agent host ``` The core has no Tauri dependency, so the same operations layer serves both the GUI and the hub. An agent and the app can write concurrently because every mutation takes the same cross-process lock; a file watcher pushes the agent's changes back into your window. The layer diagram, the event names and the module map are in [reference/architecture](https://white1024.github.io/ai-pos/reference/architecture/). ## Development ```bash pnpm tauri dev # run the app in development pnpm build # typecheck + build the web layer pnpm test # frontend unit tests (vitest) cargo test --workspace # must be fully green before committing ``` See [reference/building](https://white1024.github.io/ai-pos/reference/building/) for the test suite, packaging, and the unsigned-build notes, and [CONTRIBUTING.md](CONTRIBUTING.md) for the repository layout, the layering rules enforced under `src/`, and how a change reaches this repository. > [!NOTE] > This project is built with the method it ships: an engine-maintained state block at the entry point, a layered operations guide, one-fact-per-file memory, and gates evaluated against real state rather than self-reported. Its own research record — decisions, roadmap, session log — is kept in Traditional Chinese for maintainers and stays out of this mirror. ## Status In active development. [v0.1.0](https://github.com/white1024/ai-pos/releases/latest) is the first pre-release: unsigned trial builds for three platforms, with no auto-update yet. **Working** — the workspace engine and disk contract; the phase/gate harness and its built-in templates; the handoff layer; the hub MCP server with per-tool authorisation; the embedded agent terminal, including custom CLI entries carrying environment variables, which is how you point one at a local model; adopting an existing project through a wizard that analyses read-only and never overwrites; milestones; full-text search; portable backups. As opt-in modules: collaboration, teams and cross-project delivery, and the spec layer. **Not there yet** — signed installers and auto-update; in the teams module, automatic "a delivery arrives → a task is created" (turning one into a task manually is one click today), and scheduling. ## License [MIT](LICENSE).