> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/readme.md).

# FactionOS

**Mission control for AI coding agents.**

<p align="center"><a href="https://github.com/AI-with-Apex-VIP/factionos/tree/main/package.json"><img src="https://img.shields.io/badge/version-0.3.7-0f766e" alt="Version 0.3.7"></a> <a href="https://github.com/AI-with-Apex-VIP/factionos/tree/main/package.json"><img src="https://img.shields.io/badge/node-%3E%3D26.2.0-339933?logo=nodedotjs&#x26;logoColor=white" alt="Node 26.2.0 or newer"></a> <a href="https://github.com/AI-with-Apex-VIP/factionos/tree/main/package.json"><img src="https://img.shields.io/badge/npm-workspaces-CB3837?logo=npm&#x26;logoColor=white" alt="npm workspaces"></a> <a href="https://github.com/AI-with-Apex-VIP/factionos/tree/main/package.json"><img src="https://img.shields.io/badge/package-private-111827" alt="Private workspace"></a> <a href="/pages/YZ5uHFZpqSTvviqGd3Xx"><img src="https://img.shields.io/badge/local--first-core-16a34a" alt="Local first"></a> <a href="/pages/DF6TdeUCCm2AhmJ42CUC"><img src="https://img.shields.io/badge/provider--neutral-protocol-2563eb" alt="Provider neutral"></a> <a href="/pages/6GQCAp44QZBvZSfIpapf"><img src="https://img.shields.io/badge/Claude%20Code-hooks-7c3aed" alt="Claude Code hooks"></a> <a href="/pages/6GQCAp44QZBvZSfIpapf"><img src="https://img.shields.io/badge/Codex%20CLI-hooks-0891b2" alt="Codex CLI hooks"></a> <a href="/pages/guhEBHbQJotvqzabVFkh"><img src="https://img.shields.io/badge/event%20API-compatible-0f766e" alt="Generic event API"></a> <a href="https://github.com/AI-with-Apex-VIP/factionos/tree/main/apps/server/package.json"><img src="https://img.shields.io/badge/Express-5.2.1-000000?logo=express&#x26;logoColor=white" alt="Express 5.2.1"></a> <a href="https://github.com/AI-with-Apex-VIP/factionos/tree/main/apps/server/package.json"><img src="https://img.shields.io/badge/ws-8.21.0-111827" alt="WebSocket ws 8.21.0"></a> <a href="https://github.com/AI-with-Apex-VIP/factionos/tree/main/apps/web/package.json"><img src="https://img.shields.io/badge/React-19.2.6-61DAFB?logo=react&#x26;logoColor=111827" alt="React 19.2.6"></a> <a href="https://github.com/AI-with-Apex-VIP/factionos/tree/main/package.json"><img src="https://img.shields.io/badge/Vite-8.0.16-646CFF?logo=vite&#x26;logoColor=white" alt="Vite 8.0.16"></a> <a href="https://github.com/AI-with-Apex-VIP/factionos/tree/main/packages/protocol/README.md"><img src="https://img.shields.io/badge/TypeScript-contracts-3178C6?logo=typescript&#x26;logoColor=white" alt="TypeScript contracts"></a> <a href="https://github.com/AI-with-Apex-VIP/factionos/tree/main/biome.jsonc"><img src="https://img.shields.io/badge/code%20style-Biome-60A5FA" alt="Biome code style"></a> <a href="/pages/wYH29K2TuiWadISvWIls"><img src="https://img.shields.io/badge/Cloudflare%20Workers-optional-F38020?logo=cloudflareworkers&#x26;logoColor=white" alt="Cloudflare Workers optional"></a> <a href="/pages/uwbIHpI75QGrbOceIORl"><img src="https://img.shields.io/badge/Discord-adapter-5865F2?logo=discord&#x26;logoColor=white" alt="Discord adapter"></a> <a href="/pages/uwbIHpI75QGrbOceIORl"><img src="https://img.shields.io/badge/Telegram-adapter-26A5E4?logo=telegram&#x26;logoColor=white" alt="Telegram adapter"></a> <a href="/pages/uwbIHpI75QGrbOceIORl"><img src="https://img.shields.io/badge/HTTPS-webhooks-374151" alt="HTTPS webhooks"></a> <a href="/pages/oTGFEoNyxC0gLCvPcBQK"><img src="https://img.shields.io/badge/onboarding-ready-22c55e" alt="Onboarding ready"></a> <a href="/pages/pkppLNVcH3fSQ9PDD1zP"><img src="https://img.shields.io/badge/developer-cockpit-0f172a" alt="Developer cockpit"></a> <a href="/pages/gIjz5bCptNn6EbqdfLz0"><img src="https://img.shields.io/badge/architecture-documented-4f46e5" alt="Architecture documented"></a> <a href="/pages/YZ5uHFZpqSTvviqGd3Xx"><img src="https://img.shields.io/badge/privacy-reviewed-059669" alt="Privacy reviewed"></a> <a href="/pages/pdOvCcbYTXagUGgDZChQ"><img src="https://img.shields.io/badge/deployment-docs-2563eb" alt="Deployment docs"></a> <a href="/pages/MKB8B1tPfYdqxq81GdjC"><img src="https://img.shields.io/badge/public%20demo-static-f59e0b" alt="Public demo static"></a> <a href="/pages/ev3elRPLIVn5lgMYJ1QI"><img src="https://img.shields.io/badge/release%20gates-documented-7c3aed" alt="Release gates documented"></a> <a href="/pages/J7wQkwUvC1ErUH1fzY3A"><img src="https://img.shields.io/badge/docs-indexed-475569" alt="Docs indexed"></a></p>

<div align="center"><img src="/files/FlciO1SRpymE5Y1QhRx5" alt="FactionOS animated battlefield through dusk, combat, victory, and night watch" width="100%"></div>

FactionOS is mission control for AI coding agents - a platform that both observes and commands multi-agent workflows from a single cockpit. It streams Claude Code, Codex CLI, and compatible agent events in real time, rendering prompts, tool calls, approvals, file activity, mission state, outcomes, and replays as a live command surface. It also exposes operator controls, approval workflows, guarded action surfaces, orchestration interfaces, and multi-agent coordination tooling so teams can actively direct agent work - not just watch it.

Observability and control are co-equal design goals: metrics, event streams, timelines, and audit trails give full situational awareness; approval surfaces, mission steering, guarded actions, and orchestration hooks give operators the authority to act. The product is local-first by design: no hosted account is required for the core workflow, sensitive developer context stays on the machine unless an optional integration is explicitly configured, and the platform exposes a typed protocol for future agent and collaboration surfaces.

## Fast Answers

| Question                                           | Answer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| What is this project?                              | A local-first observability and orchestration platform for AI coding agents. It gives agent work a cockpit, event stream, mission model, audit trail, and operator controls.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Who is it for?                                     | Engineering teams, founders, AI platform leads, developer tooling teams, and power users running multiple coding agents across real projects.                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| What does it do now?                               | Streams Claude Code and Codex CLI activity into a live web cockpit, ships canonical Notice Board coordination, Quest Board suggestion/scan workflows, and local Command Center orchestration surfaces, ships a static `public-website/` commercial site with the home, product, features, how-it-works, blog, and news routes, and includes roster, mission log, battlefield view, approvals, guarded action controls, file/tool timelines, replay/export, diagnostics, optional War Room multi-agent coordination, local proposal-first channel/webhook intake, and outbound notification adapters. |
| How do I install/run/use it?                       | Use Node 26.2.0+, run `npm install`, start with `npm run dev`, then install hooks with `factionos init --cli claude`, `--cli codex`, or `--cli all`.                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| What environments or integrations are supported?   | Local Node/npm workspace, modern browser cockpit, Claude Code hooks, Codex CLI user-level hooks, the generic `/event` API, optional Cloudflare Worker War Room, outbound Discord, Telegram, or generic HTTPS webhooks, and local proposal-first GitHub/generic webhook intake.                                                                                                                                                                                                                                                                                                                       |
| How do I test or verify it?                        | Run `npm run format:check`, `npm run lint`, `npm run typecheck`, `npm test`, `npm run build`, and `npm run test:e2e` when browser coverage is needed.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Where are deeper docs?                             | Start with [`docs/README_docs.md`](/faction-os-docs/docs/readme_docs.md), [`docs/onboarding.md`](/faction-os-docs/docs/onboarding.md), [`docs/ARCHITECTURE.md`](/faction-os-docs/docs/architecture.md), [`public-website/README_public-website.md`](/faction-os-docs/public-website/readme_public-website.md), and [`docs/api/README_api.md`](/faction-os-docs/docs/api/readme_api.md).                                                                                                                                                                                                              |
| What is the support/security/contribution posture? | Proprietary licensed, active local-first workspace, Node 26.2.0+ baseline, privacy-sensitive by default, loopback-first local runtime, explicit optional integrations, and PRs welcome through [`CONTRIBUTING.md`](/faction-os-docs/contributing.md).                                                                                                                                                                                                                                                                                                                                                |

## Why It Matters

AI coding agents are becoming real operators in software delivery. Teams need the full control plane: see what agents are doing, intervene when they go wrong, approve risky actions before they execute, orchestrate work across multiple concurrent sessions, coordinate agent teams, replay and audit outcomes, and preserve local privacy - without turning every terminal into a blind spot.

FactionOS provides that control plane - both the visibility layer and the command layer:

* **Live observability:** every session becomes a mission with status, activity, tools, files, approvals, summaries, and outcomes - full situational awareness across all running agents simultaneously.
* **Active operator control:** approval workflows, guarded action proposals, mission steering, and orchestration surfaces give operators the authority to direct agent behavior in real time, not just observe it.
* **Multi-agent system management:** the cockpit is purpose-built for running, comparing, and coordinating multiple concurrent agent sessions - roster views, per-mission timelines, standings, cross-session replay, and team coordination through the optional War Room.
* **Provider-neutral architecture:** Claude Code and Codex CLI are supported today, with shared event contracts and orchestration interfaces for compatible agent producers.
* **Local-first trust model:** the core runtime works on the developer machine without a hosted account, database, analytics service, or cloud dependency.
* **Expansion path:** optional War Room, adapters, protocol packages, and guarded hosted-service contracts let the platform grow without weakening the local privacy boundary.

## Product Surface

| Surface        | What ships today                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Web cockpit    | Live roster, mission history, mission detail, hero detail, command palette, battlefield view, standings, leaderboard, replay, export, notifications, settings, diagnostics, focused bottom-rail Quest Board/Command Center/War Room surfaces, and stable local preferences. **Operator controls, approval surfaces, guarded action interfaces, and orchestration panels are first-class features of the cockpit.**                                       |
| Command Center | Local orchestration cockpit for campaigns, attention, executor capability posture, File/Git workbench, bounded terminal/container controls, mission artifacts, collaboration and handoff posture, channels, metrics, notifications, shortcuts, and adjacent-surface links. Operators reach it through the bottom-rail Orchestration card and focused surface. Channel intake is proposal-first, and remote/hosted execution remains a no-claim boundary. |
| Hook ingest    | Provider-aware hook handlers and source maps for Claude Code and Codex CLI, plus a tolerant HTTP event endpoint for compatible producers.                                                                                                                                                                                                                                                                                                                |
| CLI            | `factionos init`, `start`, `open`, `stop`, `status`, `doctor`, and `uninstall` for local setup and lifecycle management.                                                                                                                                                                                                                                                                                                                                 |
| Notice Board   | Canonical local coordination board with post/list/context/resolve commands, automatic mission lifecycle notices, hook prompt-start context, and optional Worker relay.                                                                                                                                                                                                                                                                                   |
| Quest Board    | Manager-owned suggestion and scan board with accept/dismiss actions, summaries, codebase analysis, project scan orchestration, typed cards, and keyboard shortcuts.                                                                                                                                                                                                                                                                                      |
| Protocol       | Shared TypeScript contracts for events, missions, heroes, plans, notices, suggestions, scans, achievements, scrolls, factions, guarded actions, orchestration, War Room, and hosted-service posture.                                                                                                                                                                                                                                                     |
| Collaboration  | Optional Cloudflare Worker and Durable Object War Room backend for multi-agent coordination: room lifecycle, approval, presence, reconnect, and redacted federation.                                                                                                                                                                                                                                                                                     |
| Adapters       | Outbound Discord, Telegram, and generic HTTPS webhook bridges for notifications and integration. Adapters remain outbound; inbound GitHub/generic webhook intake lives under local Command Center channel routes, is proposal-first, and does not run trusted remote commands.                                                                                                                                                                           |
| Demo           | Static zero-install public demo with synthetic data in [`public-demo/`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/public-demo/README.md).                                                                                                                                                                                                                                                                                                  |
| Public website | Static `public-website/` surface for the main `faction-os.com` website: landing page, product story, blog, news, investor-related material, and links to the demo and public docs.                                                                                                                                                                                                                                                                       |

## Quick Start

```bash
npm install
npm run dev
```

The root dev script starts:

* local server: [`http://127.0.0.1:2468`](http://127.0.0.1:2468)
* web cockpit: [`http://localhost:5193`](http://localhost:5193)

The server can run mock events, so the cockpit is useful before real hooks are installed.

To use the shipped local orchestration controls, open the cockpit and follow [`docs/orchestration-quickstart.md`](/faction-os-docs/docs/orchestration-quickstart.md).

## Stream Real Agents

First link the local CLI from this workspace:

```bash
npm --workspace apps/cli link
```

Install the hook target you want:

```bash
# Claude Code
factionos init --cli claude --faction orc

# Codex CLI
factionos init --cli codex --faction orc

# Both Claude Code and Codex CLI
factionos init --cli all --faction orc
```

Then start FactionOS and open the cockpit:

```bash
factionos start --daemon
factionos open
```

Start Claude Code and/or Codex CLI from separate terminals. For Codex CLI, review loaded hooks with `/hooks` in the new Codex session. FactionOS installs user-level Codex hooks, preserves user-owned hooks, and does not create trusted project-local `.codex/` state or bypass Codex hook review.

## Zero-Install Demo

Open [`public-demo/index.html`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/public-demo/index.html) directly in a browser, or serve the public demo locally:

```bash
npm run local-demo
```

Then open [`http://127.0.0.1:8101/factionos/`](http://127.0.0.1:8101/factionos/). The demo uses synthetic data and does not connect to a local FactionOS server or real agent sessions.

## Supported Integrations

| Integration                                      | Status                         | Notes                                                                                                                                                                                                                                      |
| ------------------------------------------------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Claude Code                                      | Supported local hook target    | `factionos init --cli claude` installs FactionOS-managed Claude hooks while preserving user-owned settings where possible.                                                                                                                 |
| Codex CLI                                        | Supported local hook target    | `factionos init --cli codex` installs user-level managed hooks into `CODEX_HOME` or the Codex user config directory. Users review trust with `/hooks`.                                                                                     |
| Claude + Codex together                          | Supported                      | `factionos init --cli all` installs both hook maps; run each agent in its own terminal.                                                                                                                                                    |
| Generic agent producers                          | Supported through API          | Compatible tools can post events to the local `/event` endpoint using the shared protocol contracts.                                                                                                                                       |
| Cloudflare War Room                              | Optional                       | Worker and Durable Object backend for room collaboration. Core local use does not require it.                                                                                                                                              |
| Discord, Telegram, HTTPS webhooks                | Optional outbound              | Notification adapters are best-effort and outbound only.                                                                                                                                                                                   |
| GitHub and generic webhook intake                | Optional local proposal intake | Local `/channels`, `/channel-commands`, `/webhooks/generic`, and `/webhooks/github` routes record bounded command rows for operator review. They do not verify GitHub signatures in this phase and do not execute trusted remote commands. |
| Hosted identity, hosted storage, analytics, push | Not required for core workflow | Guardrail contracts and docs exist, but core FactionOS is local-first and these surfaces are not required for the shipped local path.                                                                                                      |

## Verify The Workspace

Use the relevant subset for your change:

```bash
npm run format:check
npm run lint
npm run typecheck
npm test
npm run build
npm run security:secrets
```

For browser and release confidence:

```bash
npm run test:e2e
npm run media:check
npm run media:visual:check
npm run media:demo:check
npm run battlefield:check
npm run media:gates:check
```

CI coverage lives in:

* [`.github/workflows/quality.yml`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.github/workflows/quality.yml)
* [`.github/workflows/test.yml`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.github/workflows/test.yml)
* [`.github/workflows/e2e.yml`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.github/workflows/e2e.yml)
* [`.github/workflows/security.yml`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.github/workflows/security.yml)
* [`.github/workflows/pages.yml`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.github/workflows/pages.yml)

## Workspace Map

| Package                                                                                                    | Purpose                                                                                                                                                                                             |
| ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`apps/server`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/apps/server/README.md)             | Local Express and WebSocket runtime.                                                                                                                                                                |
| [`apps/web`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/apps/web/README.md)                   | Vite React browser cockpit and battlefield UI.                                                                                                                                                      |
| [`apps/hooks`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/apps/hooks/README.md)               | Hook handlers, provider-specific source maps, and listener bridge.                                                                                                                                  |
| [`apps/cli`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/apps/cli/README.md)                   | Local installer, lifecycle commands, status, doctor, and uninstall.                                                                                                                                 |
| [`apps/warroom`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/apps/warroom/README.md)           | Optional Cloudflare Worker and Durable Object collaboration backend.                                                                                                                                |
| [`apps/adapters`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/apps/adapters/README.md)         | Outbound Discord, Telegram, and webhook bridges.                                                                                                                                                    |
| [`packages/protocol`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/packages/protocol/README.md) | Shared event, domain, War Room, and hosted-posture contracts.                                                                                                                                       |
| [`public-demo`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/public-demo/README.md)             | Static synthetic-data demo.                                                                                                                                                                         |
| `public-website/`                                                                                          | Static Astro workspace for the main `faction-os.com` website: shipped home, product, features, how-it-works, blog, and news routes plus phase-scoped conversion pages and external demo/docs links. |

Root `README.md` is the current project front page. Package-specific guidance lives in directory-level `README_<name>.md` files.

## Deeper Docs

| Need                    | Start here                                                                               |
| ----------------------- | ---------------------------------------------------------------------------------------- |
| Documentation index     | [`docs/README_docs.md`](/faction-os-docs/docs/readme_docs.md)                            |
| First local setup       | [`docs/onboarding.md`](/faction-os-docs/docs/onboarding.md)                              |
| Architecture            | [`docs/ARCHITECTURE.md`](/faction-os-docs/docs/architecture.md)                          |
| Development workflow    | [`docs/development.md`](/faction-os-docs/docs/development.md)                            |
| API and event contracts | [`docs/api/README_api.md`](/faction-os-docs/docs/api/readme_api.md)                      |
| Hook contracts          | [`apps/hooks/README_hooks.md`](/faction-os-docs/apps/hooks/readme_hooks.md)              |
| CLI behavior            | [`apps/cli/README_cli.md`](/faction-os-docs/apps/cli/readme_cli.md)                      |
| Privacy and security    | [`docs/privacy-and-security.md`](/faction-os-docs/docs/privacy-and-security.md)          |
| Deployment and CI       | [`docs/deployment.md`](/faction-os-docs/docs/deployment.md)                              |
| Release gates           | [`docs/release.md`](/faction-os-docs/docs/release.md)                                    |
| Public docs website     | [`faction-os.gitbook.io/faction-os-docs`](https://faction-os.gitbook.io/faction-os-docs) |

## Posture

FactionOS is built as a local-first developer platform. The supported core path is the Node 26.2.0+ local runtime, local web cockpit, Claude Code and Codex CLI hook targets, and compatible event producers through the local API.

Security-sensitive data can include prompts, file paths, command previews, tool metadata, summaries, local identifiers, replay buffers, exports, adapter payloads, and optional code-analysis content. The local server binds to loopback by default, restricts default CORS and WebSocket origins to local dev origins, and can enforce HTTP/WebSocket bearer auth with `FACTIONOS_AUTH_TOKEN`.

Core FactionOS does not require hosted identity, hosted storage, analytics, push, public replay hosting, or remote execution. Optional integrations must be configured intentionally and are documented in [`docs/privacy-and-security.md`](/faction-os-docs/docs/privacy-and-security.md) and [`docs/hosted-services.md`](/faction-os-docs/docs/hosted-services.md).

Contributions are welcome. Use [`CONTRIBUTING.md`](/faction-os-docs/contributing.md), keep one logical change per PR, run the relevant checks, and call out privacy, security, hosted-service, adapter, or media-provenance impact when behavior changes.

## License

FactionOS is maintained by [@moshehbenavraham](https://github.com/moshehbenavraham) and is proprietary software. All rights reserved. See [`LICENSE`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/LICENSE/README.md) for details.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/readme.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.