factor-q

A single-tenant, self-hosted agent runtime for designing, operating, and evolving multi-agent systems that deliver on large, ongoing projects.

factor-q is not a chatbot or an interactive coding assistant. It is a continuously running, event-driven agent orchestrator where human interaction is one input among many. Where most agent harnesses serve the build part of the lifecycle, factor-q is built for continuous operation of ongoing processes — see the Vision.

Key properties

• Event-driven — every agent interaction is an event on a NATS-based event bus, enabling auditing, replay, and debugging
• Model-agnostic — each agent in a graph targets the model best suited to its task, mixing providers freely
• Headless-first — runs as a persistent server; CLI, TUI, and other interfaces are clients of the runtime
• Cost-aware — budget limits and spending controls built in from the start
• Extensible — custom tools via subprocess/MCP; agent definitions as Markdown files, graph definitions as YAML

Documentation

• Status — one screen: what runs today, where we are, what's next
• Security posture — current security limitations and vulnerability reporting
• Quickstart — clone to running agent in under ten minutes
• Vision — what factor-q is and why it exists
• Architecture — core subsystems and implementation
• Design principles — cross-cutting rules that guide design decisions
• Contributing — development setup, test tiers, code conventions
• Agent authoring guide — write your first agent
• Reasoning models — what happens to a model's reasoning per provider and route, and where it does not yet carry
• Reducer harness guide — the suspend/resume-capable execution path that drives every invocation
• Operating the daemon — notification and alert vocabulary, stop and redeploy (fq down; relaunch after stopping to redeploy), hot-reload (fq reload) a running daemon cleanly, and re-derive its projection from the event stream (fq projection rebuild)
• Content storage (fq-cas) — the content-addressed store CLI + library (Phase 2 pillar #2)
• Event schema — the event model everything is built around
• Agent orchestration tools — wishlist for primitives to coordinate multi-agent work (graph substrate, handles, sinks, fragment library)
• Worker-side ergonomics — primitives for what an agent has, knows, and controls while executing (introspection, checkpoints, structured errors)
• Storage and scaling — sizing analysis for NATS and SQLite
• Storage garbage collection — the lock-free online-reclaim protocol for the CAS (M1c)
• Reference workloads — concrete agent workloads (Canopy, TradingAgents) we use as design touchstones
• ADRs — architectural decision records (accepted, draft)
• Phase 1 (closed) — what shipped in the walking skeleton
• Phase 2 (active) — MCP, memory, and skills
• Issues — deferred work and the dispatch queue

Technology

• Runtime: Rust
• Event bus: NATS + JetStream
• Projections: SQLite
• Agent definitions: Markdown with YAML frontmatter
• Graph definitions: YAML with JSON Schema

Project structure

factor-q/
├── Cargo.toml                 The single Cargo workspace (#194) — every Rust
│                              crate below shares one Cargo.lock and target/
├── services/fq-runtime/       Runtime crates
│   └── crates/
│       ├── fq-agent/            agent definitions (model, parser, registry)
│       ├── fq-cli/              the fq operator client (CLI commands)
│       ├── fq-daemon/           the fqd daemon binary (boot, host, control)
│       ├── fq-edge/             authenticated generic edge (wire transport)
│       ├── fq-ops/              operation-registry contract crate
│       ├── fq-runtime/          core library (bus, executor, projection, dispatcher)
│       └── fq-tools/            built-in tools and sandbox enforcement
│
├── services/fq-store/         Content-addressed storage + index (fq-cas CLI)
├── services/fq-dashboard/     Operator dashboard (read-only web surface)
├── services/fq-test-support/  Test-only helpers shared across services
│
├── infrastructure/            Deployment and local dev
│   ├── docker-compose.yml       NATS + JetStream
│   └── nats/                    NATS server configuration
│
├── adapters/                  Standalone trigger adapters — talk to factor-q
│   ├── fq-cron/                 durable cron scheduler (Go)
│   └── github-watcher/          polls a repo for `status:ready` issues (Go)
│
├── agents/examples/           Sample agent definitions
├── tests/smoke/               End-to-end smoke tests against a real LLM
│
├── docs/
│   ├── adrs/                  Architectural decision records
│   ├── design/                Event schema, storage and scaling specs
│   ├── guide/                 User-facing guides (agent authoring)
│   └── plans/                 Phase plans (active + closed)
│
├── VISION.md
├── ARCHITECTURE.md
├── CONTRIBUTING.md
└── README.md

Install

Until the first release, build factor-q from source, as in the Quickstart:

git clone https://github.com/bricef/factor-q.git
cd factor-q
just up

This starts NATS+JetStream in Docker and builds fq and fqd. Use it through just fq:

mkdir my-project && cd my-project
just fq init                            # writes fqd.toml, fq.toml, agents/, sample agent
export ANTHROPIC_API_KEY='sk-ant-...'

just run                                # (another terminal) start the daemon —
                                        # on its first run it prints a fingerprint
                                        # and writes the admin token to
                                        # ~/.local/state/factor-q/edge/admin.token
just fq connect 127.0.0.1:9472 --token "$(cat ~/.local/state/factor-q/edge/admin.token)"

just fq trigger sample-agent "Hello."   # run the agent
just fq events tail                     # watch events

Every fq verb answers over the daemon's authenticated edge, so the daemon has to be up and this client has to be paired with it before any of them work.

Pre-built binary installs via install.sh will be available after the first release.

Getting started

See QUICKSTART.md for the full step-by-step path from a fresh clone to a running agent with event-trail inspection. The short version:

just up                                 # NATS + build
mkdir my-project && cd my-project
just fq init                            # writes fqd.toml, fq.toml, agents/, sample
export ANTHROPIC_API_KEY='sk-ant-...'
just run                                # (another terminal) start the daemon
just fq connect 127.0.0.1:9472 --token "$(cat ~/.local/state/factor-q/edge/admin.token)"   # written once, at first run
just fq trigger sample-agent "Hello."   # run the agent
just fq events tail                     # watch events

For development setup and test tiers, see CONTRIBUTING.md.

Prior Art

• Crush — architecture analysis
• OpenCode — architecture analysis
• open-agent.io

License

factor-q is licensed under the Business Source License 1.1. Personal, non-commercial use by individuals is free; any organizational or commercial use requires a commercial license — contact licensing@factorq.top. Each release converts to Apache-2.0 four years after publication.