exe-os

AI employee operating system for AskExe: local-first memory, identity, task orchestration, and runtime glue for managing AI teammates through Claude Code, Codex, OpenCode, and the emerging desktop/runtime stack.

Current npm package: @askexenow/exe-os v0.9.341. Node.js >=20 required.

What this repo is for

exe-os lets a founder run an AI org instead of a single chat session:

• A coordinator agent owns the founder conversation and delegates through tracked tasks.
• Specialists run in isolated tmux/worktree sessions with persistent identity, behaviors, and memory.
• The local daemon, MCP server, hooks, and CLI keep sessions, reminders, reviews, cloud sync, and diagnostics connected.
• Customer data stays local-first and encrypted; cloud sync is end-to-end encrypted when enabled.

Hard constraints for every change:

• MCP is the only data interface. Never access the SQLCipher DB directly.
• Preserve customer data sovereignty. Updates must not overwrite identities, behaviors, procedures, rosters, local memory, or user config.
• No secrets in code, logs, tests, telemetry, or bug reports.
• No require() in runtime ESM TypeScript under src/lib, src/mcp, or src/tui; use ESM imports.
• Every task/review/message/notification query must filter by session_scope.
• No hardcoded employee names. Use role/config resolution, not AskExe's local roster.

Architecture at a glance

User / founder
  -> coordinator agent session
     -> managers / specialists via task DB + tmux sessions

Claude Code / Codex / OpenCode
  -> hooks + MCP tools
     -> exe daemon
        -> encrypted local memory/tasks/identity/behavior store
        -> optional E2EE cloud sync
        -> gateway / stack integrations

Key pieces:

• MCP server (src/mcp) exposes the supported tool surface for memory, tasks, identity, behavior, support, diagnostics, config, documents, CRM/raw data, and gateway actions.
• Daemon (src/lib, src/services) supervises sessions, timers, task enforcement, intercom delivery, sync, diagnostics, and local state.
• Adapters (src/adapters) integrate with Claude Code, Codex, and OpenCode through hooks and launcher behavior.
• CLI commands (src/bin, src/commands) install, launch, diagnose, update, release, preflight, sync, and operate the stack.
• Runtime/TUI (src/runtime, src/tui) are legacy/current terminal runtime surfaces; the architecture doc notes the legacy Ink TUI is frozen while the product direction moves toward the native exe-build/desktop chat runtime.
• Stack deploy (deploy) contains compose, manifests, observability, registry proxy, nginx, migrations, and customer VPS deployment assets.

Cognition layers used by agents:

1. Company procedures: org-wide rules.
2. Identity: role definition and non-negotiables.
3. Behaviors/expertise: learned corrections and skills.
4. Experience/memory: searchable history and decisions.
5. Prospective items: future-condition memory/reminders surfaced at boot.

Repo map

| Path | Purpose | |---|---| | src/lib/ | Core daemon/runtime libraries: memory, tasks, identity, behaviors, search, sync, config, orchestration. | | src/mcp/ | Consolidated MCP server and tool implementations. This is the supported data/control boundary. | | src/adapters/ | Claude/Codex/OpenCode integration hooks and adapter glue. | | src/bin/ | CLI entrypoints published through package.json#bin. | | src/commands/ | Command implementations for exe-os, setup/update/release flows, diagnostics, etc. | | src/runtime/ | Agent runtime/tool registry pieces. | | src/tui/ | Legacy Ink TUI surface; avoid new product investment unless explicitly tasked. | | src/gateway/ | Gateway/provider adapters and external messaging integration code. | | deploy/ | Customer stack compose files, manifests, migrations, nginx, observability, registry proxy, Ansible. | | deploy/stack-manifests/ | Customer-facing stack manifests; images must be digest-pinned. | | packages/ | Shared UI/theme/health/error-page packages. | | tests/ | Vitest suites, smoke tests, deploy tests, integration tests, orchestration tests. | | scripts/ | Build locks, guards, schema checks, stack simulation, preflight helpers. | | .planning/ARCHITECTURE.md | Source of truth for current architecture and shipped progress. Future roadmap belongs in MCP support feature records, not markdown. | | release-notes.json | Current npm release notes shown after updates. | | stack.release.json | Stack release descriptor for customer/VPS participation. |

Key commands

Customer/operator commands published by this package:

| Command | Use | |---|---| | exe | Launch the configured coordinator agent. | | exe-os | Main CLI/dashboard entry. | | exe-os setup | First-time setup wizard: encryption, license, team, hooks, MCP, daemon. | | exe-os update | Recommended interactive update path for installed systems. | | exe-os healthcheck / exe-healthcheck | Health check for daemon, memory, cloud/sync, retrieval, and runtime state. | | exe-doctor | Deeper diagnostics. | | exe-pending-reviews | Show review queue; use before claiming work is idle/done. | | exe-pending-messages | Show pending inter-agent messages. | | exe-config-dump | Read-only effective config dump with secret redaction. | | exe-timers | Timer health dashboard. | | exe-search-quality | Retrieval quality/latency telemetry. | | exe-stack-update | Customer stack image update flow. Run only with explicit approval. | | exe-preflight | Stack/client production preflight checks. | | exe-cloud | Cloud sync/linking commands. Never print recovery phrases in agent output. |

Useful local checks:

npm run typecheck
npm run lint
npm test
npm run test:daemon-smoke
npm run test:stack-sim
npm run guard:esm-require
npm run check:schema-version
npm run build

Development workflow

Install dependencies:

npm install

Before coding:

1. Read the task brief and source docs.
2. Use code-context/MCP search when available before broad manual grep.
3. Keep diffs surgical; do not reformat unrelated files.
4. Do not touch customer-local data, identities, behaviors, procedures, or rosters.

Standard validation:

npm run typecheck
npm test
npm run build

Targeted validation is acceptable for small changes, but release/merge gates require the relevant full checks. For runtime/daemon-critical work, also run:

npm run guard:esm-require
npm run test:daemon-smoke

Build details:

• npm run build uses scripts/build-lock.sh, then copies runtime assets into dist/ and generates hook manifests when possible.
• npm run deploy builds, installs this checkout globally, and restarts/re-registers pieces. It disrupts active MCP sessions; do not run it casually.
• postinstall runs command-only install behavior so global installs expose CLIs without overwriting customer data.

Test and CI notes

• Main test runner: vitest run.
• test:publish is the required publish gate subset plus selected serialized stress/gateway tests.
• Tests that touch support/bug/feature upstream paths must mock fetch; never create live support records from tests.
• Docker/live-DB tests may be quarantined in test:publish; read the script comments before assuming a missing test is accidental.
• CI must be green on the exact commit before merge/release.

Publish and release

NPM publish gate:

npm run prepublishOnly

That runs typecheck, build, orphan chunk pruning, ESM require() guard, schema version check, customer-readiness, and pre-publish checks.

Normal local package update path for users:

npm install -g @askexenow/exe-os@latest
# or use the interactive path
exe-os update

Customer stack releases are separate from npm package releases:

• release-notes.json currently tracks npm v0.9.341.
• stack.release.json currently describes stack/source v0.9.312 and includes TODO notes for private GHCR app image digest resolution.
• Customer stack manifests/images must be SHA256 digest-pinned. Do not promote tag-only app images to customer releases.
• Production stack updates must preserve named Docker volumes and customer state; never use docker compose down -v or remove data volumes.
• Stack image release should go through the documented exe-os release --stack flow, Bob/customer-readiness audit, preflight, pinned images, and health verification.

Operational gotchas

• MCP only. If MCP is disconnected, reconnect it; do not bypass with direct DB reads or ad-hoc scripts against SQLCipher.
• Session scope matters. Cross-session task/review/message leakage is a P0 class bug. Query filters must include session_scope where applicable.
• Data is immutable unless the user changes it. Installers, updates, imports, starter packs, and stack updates must be additive/check-exists-first.
• Cloud endpoint is https://api.askexe.com. Do not introduce legacy cloud domains.
• Key material belongs in Keychain/secret-tool. Never log, print, or commit recovery phrases or master keys.
• Runtime TypeScript is ESM. require() in daemon/MCP/TUI runtime paths will break after build.
• Stack state needs volumes. WhatsApp auth, Postgres, wiki/CRM/gateway data, monitor data, and other stateful services need named volumes before image swaps.
• Health before claims. Verify daemon health, pending reviews, pending messages, task status, and tmux state before reporting an agent is idle/done/stuck.
• Build after merges. A clean git merge is not a build check; run npm run build after merged work that affects shipped code.
• No :latest in manifests/compose. Release images must be versioned and digest-pinned for customer deploys.

Security checklist for reviews

• No secrets, PII, API keys, recovery phrases, or tokens in code/test fixtures/log output.
• Auth middleware and permission checks preserved.
• External network connections use TLS unless explicitly local-only.
• Telemetry/bug-report egress redacts secrets and mnemonics.
• No direct DB access paths added; all agent-facing data flows through MCP tools.
• No hardcoded AskExe employee names, local paths, or private roster assumptions.
• Compose services have healthchecks and stateful services have durable volumes.

License

Proprietary. See LICENSE.