FactionOS
Open Demo(external link)Read Docs(external link)

Technical flow

From hook event to operator view.

A local pipeline turns workflow events into reviewable cockpit state.

FactionOS starts with Claude Code hooks, Codex CLI hooks, or compatible producers. Events become JSON payloads for local `/event` ingest, local server state, WebSocket updates, and cockpit views, with optional outbound adapters and optional War Room collaboration kept explicit.

  • Hookslocal
  • Commandsexample
  • Outputsoptional
Read Docs (external link)Features

Setup panels are examples only. Run commands from your own terminal after reviewing the public docs.

Hook-to-cockpit pipeline

Agent events flow into reviewable state.

Claude Code hooks, Codex CLI hooks, or compatible producers become JSON payloads for local ingest, server state, and cockpit views, with optional outbound steps kept explicit.

  1. Claude Code

    Claude Code hooks emit local workflow events.

    Configured hooks can describe prompt lifecycle, tool activity, and validation milestones.

    In Local Claude Code workflowOut Hook event

    Hook events start on the operator machine and do not require a hosted account.

  2. Codex CLI

    Codex CLI hooks use the provider-specific local map.

    Codex support installs managed user-level hook commands while leaving hook trust review to Codex.

    In Codex CLI session eventOut Managed hook event

    FactionOS does not change Codex auth, model, provider, profile, or trust settings.

  3. Compatible producers

    Other producers can follow the same event contract.

    Compatible producers can use the generic event API shape.

    In Compatible event producerOut Protocol-shaped event

    Compatibility is contract-based and does not imply every agent provider is fully supported.

  4. Protocol

    Events become JSON payloads with known fields.

    Shared contracts keep event names, timestamps, mission context, and review state aligned.

    In Hook signalOut Structured JSON payload

    Payload examples should avoid secrets, raw source, and broad local path disclosure.

  5. Local /event

    The local `/event` endpoint ingests the payload.

    The server accepts local events and turns them into product state near the workspace.

    In JSON payloadOut Accepted local event

    Ingest is local product runtime behavior, not a browser call made by this website.

  6. apps/server

    The local server normalizes mission state.

    Server logic aligns events, snapshots, lifecycle state, diagnostics, and review posture.

    In Accepted eventOut State snapshot

    Server state is not automatically hosted, indexed, or sent to analytics.

  7. WebSocket

    A WebSocket stream updates the local cockpit.

    When runtime is active, the cockpit can receive live state changes without polling public pages.

    In State changeOut Streamed cockpit update

    Public pages do not open a WebSocket or connect to a local runtime.

  8. apps/web

    The cockpit renders missions, timelines, and review state.

    Operators inspect the roster, mission feed, battlefield map, approvals, timelines, and diagnostics.

    In Snapshot and streamOut Operator view

    The product cockpit belongs to the installed runtime.

  9. Adapters

    Optional adapters send outbound notices only.

    Discord, Telegram, and generic HTTPS adapters are optional outbound paths. They receive narrow status messages only if configured.

    In Operator-approved stateOut External notification

    Adapters are not inbound command channels or remote execution paths.

  10. War Room

    Optional War Room exposes shared mission posture.

    A team-visible surface can be enabled separately when collaboration boundaries are configured.

    In Shared mission stateOut Collaborative view

    War Room collaboration is optional and separate from the local baseline. Hosted identity, storage, and public replay are separate concerns.

Setup examples

Command panels show the setup flow.

These panels show the shape of local setup and link out to the public docs for full instructions.

Example only

Install dependencies

Use the repository docs for the complete setup path and supported Node/npm versions.

npm install
npm --workspace apps/cli link

These lines are examples. Run setup from your own terminal after reviewing the docs.

Read Docs (external link)
Example only

Start local development

Local development starts product surfaces on the operator machine.

npm run dev
npm --workspace @factionos/public-website run dev
npm --workspace @factionos/public-website run typecheck

Run commands from your own terminal after reviewing the public docs and repository guidance.

Read Docs (external link)
Example only

Initialize local hooks

Provider setup is explicit: Claude Code, Codex CLI, or both can be selected by the operator.

factionos init --cli claude
factionos init --cli codex
factionos status --cli all

Codex hook trust remains a Codex review step. These examples do not bypass local trust prompts.

Read Docs (external link)

Handoff

Use examples as a map, not as an installer.

The setup panels show the shape of a local workflow. The public docs own complete setup detail, CLI guidance, and validation steps.

Read Docs (external link)Features

The website never executes terminal commands. Commands belong in an operator-controlled local shell after docs review.