Aidoki Starter Pack

This starter pack contains product and engineering documents for building Aidoki with Codex.

The project is a local-first cross-agent memory manager for AI agents such as Codex, Claude Code, and OpenCode.

Key Requirement

The MVP must include:

1. Python core engine.
2. aidoki CLI.
3. macOS menu bar UI.
4. Safe import/export/backup/restore for agent memory files.

Included Files

AGENTS.md
PRD.md
MVP_SCOPE.md
ARCHITECTURE.md
UI_SPEC.md
CLI_SPEC.md
ROADMAP.md
TASKS.md
docs/
  memory-schema.md
  adapter-contract.md
  compiler-design.md
  security-model.md
  backup-restore.md
  product-decisions.md
examples/
  codex/AGENTS.md
  claude/CLAUDE.md
  opencode/opencode.jsonc
prompts/
  codex-milestone-1.txt
  codex-milestone-2.txt
  codex-milestone-13.txt

Quickstart

Install dependencies:

uv sync

Show the CLI help:

uv run` aidoki --help

Run tests and linting:

uv run pytest
uv run ruff check .

This repository currently contains the Milestone 1 project skeleton only. Memory import, export, compilation, and the desktop UI are intentionally not implemented yet.

Try the Community App

The Community edition is distributed as a macOS .app plus a .dmg. Phase 1 ships an Apple Silicon (aarch64-apple-darwin) build; an Intel-compatible universal2 build is reachable through the same build script.

Pre-built artifacts (when available) live under dist/:

• dist/Aidoki.app — double-click to launch
• dist/Agent-Memory-<version>-arm64.dmg — installer image

Using the app

Once running the application has two surfaces:

• A Dock icon on the left side of the screen and a Cmd-Tab entry — the standard macOS app affordances. Click the Dock icon to bring the panel window to front.
• A menu-bar tray icon on the right side of the macOS menu bar — the quick-access command surface.

Closing the panel window does NOT exit the app. Use the tray menu's Quit, the Dock icon's Quit command, or Cmd-Q to exit.

Left-click the tray icon to drop a menu of high-frequency operations:

Item	What it does
(title line)	Shows the app version and the active edition (e.g. "Community Edition"). Disabled, informational only.
Main Window	Opens the panel window — the full UI surface.
Refresh Status	Runs aidoki status --json in the background and refreshes the panel if it is open.
Compile ▸	Submenu: compile for Codex (AGENTS.md), Claude (CLAUDE.md), or OpenCode (opencode.jsonc).
Run Security Scan	Runs aidoki scan --json.
Quit	Exits the application.

Re-launching the bundle (double-clicking it again while it is already running) brings the existing instance's panel to the front rather than starting a second tray icon.

First-run Gatekeeper override

Phase 1 bundles are not signed or notarized. On the first launch macOS will refuse to open the app. Two options:

1. Right-click Aidoki.app in Finder, choose Open, then confirm.
2. Or strip the quarantine flag once:

   xattr -d com.apple.quarantine "/Applications/Aidoki.app"

Power-user CLI

The CLI is bundled inside the .app and not added to your PATH automatically. Find it at:

/Applications/Aidoki.app/Contents/MacOS/aidoki

If you want it on your shell PATH, add an alias to ~/.zshrc or ~/.bashrc yourself, for example:

alias aidoki='/Applications/Aidoki.app/Contents/MacOS/aidoki'

The bundled CLI loads the Community manifest by default; set AIDOKI_EDITION_MANIFEST=/path/to/some.yaml to override.

Verify the bundle contains no Team code

The Community bundle physically excludes the aidoki_team package. Verify with:

grep -l aidoki_team "/Applications/Aidoki.app/Contents/MacOS/aidoki" \
  || echo "ok: no aidoki_team in bundle"

Build the App Yourself

Prerequisites on a fresh Apple Silicon Mac:

• Xcode Command Line Tools (xcode-select --install)
• Rust toolchain (rustup)
• Node + npm
• uv (curl -LsSf https://astral.sh/uv/install.sh | sh)

Build:

make app

If you change the icon design, regenerate the assets first:

make icons   # runs scripts/generate-icons.py via uv --group build

Generated assets land in desktop/src-tauri/icons/ and are committed to the repository, so day-to-day builds do not need Pillow.

Outputs land in dist/. The build script does its own smoke tests:

1. Bundled aidoki status --json returns data.edition == "community".
2. aidoki team status exits non-zero with the friendly Team-edition hint.
3. The PyInstaller archive does not contain aidoki_team.

Universal2 (Apple Silicon + Intel) is the stated product target; see openspec/changes/community-app-packaging/tasks.md section 10 for the phase-2 follow-up tasks.

Recommended Codex Start

Use this first prompt:

Read AGENTS.md, PRD.md, MVP_SCOPE.md, ARCHITECTURE.md, UI_SPEC.md, CLI_SPEC.md, and TASKS.md.

Important update:
The MVP must include a macOS menu bar UI. The UI should be built as a lightweight Tauri + React + TypeScript desktop app, but core memory business logic must stay in the Python package and CLI.

Implement Milestone 1 only:
- create Python package structure
- configure uv
- add Typer CLI entrypoint `aidoki`
- add pytest
- add ruff
- add a basic `aidoki --help`
- add a smoke test

Do not implement memory import/export.
Do not implement desktop UI yet.
Run tests and summarize changed files.

Recommended Execution Order

1. Milestone 1: Python/uv/Typer skeleton.
2. Milestone 2: Memory schema.
3. Milestone 13: Tauri menu bar UI skeleton.
4. Milestone 14: CLI JSON API for UI.
5. Milestone 15: Desktop UI calls CLI.
6. Milestone 16: Desktop diff and safe export flow.
7. Milestones 3-12: Local store, adapters, compiler, backup/restore, scanner.

Do not ask Codex to implement all milestones at once.