OrchestrIA — Agentic OS

A local-first platform to orchestrate, supervise and persist AI coding agents — Claude or OpenAI/Codex — on your own machine.

OrchestrIA is a conductor for AI agents that runs entirely on your own machine. It spawns long-lived, configurable agents — each backed by the provider you pick per agent (Claude or OpenAI/Codex) — coordinates them across channels (Telegram, webhooks), schedules recurring missions, gives every agent scoped memory, and renders the whole thing as a live web dashboard.

Nothing leaves your machine. State lives in a single SQLite file you own — no cloud database, no external sync, no telemetry. And there is no hosted API or vendor SDK: OrchestrIA drives the official claude and codex CLIs over a pseudo-terminal, so model access and billing stay inside your existing CLI sessions — no extra API key, no second bill. Not tied to a single vendor: an agent's provider is just a config field, and adding another backend is one file.

Why

Running a single coding agent is easy. Running several — each with its own role, tools, memory and triggers, and being able to see what they're all doing — is not. OrchestrIA is the missing control plane: agents become first-class objects you can create, wire together, schedule, and observe.

In practice — a daily briefing in 10 minutes

A common first build: have an agent message you a briefing every morning on Telegram. End to end, with OrchestrIA's own primitives — no n8n, no external scheduler, no glue code.

1. Wire a Telegram channel. Copy the template and drop in a BotFather token:

cp .orchestria/channels/telegram.json.example .orchestria/channels/telegram.json

{ "type": "telegram", "default_agent": "_main", "allowed_chat_ids": [], "bot_token": "<your-botfather-token>" }

2. Schedule a routine. A cron-style mission that runs an agent and pushes the result to the channel. Create it from the /routines dashboard, or via the API:

curl -X POST localhost:8000/api/routines -H 'content-type: application/json' -d '{
  "id": "morning-brief",
  "name": "Morning briefing",
  "cron_expr": "0 8 * * *",
  "agent_id": "_main",
  "prompt": "Summarise yesterday: key signals, what needs my attention, one concrete suggested action. Be concise.",
  "notify_on": "always",
  "notify_channel": "telegram"
}'

Every day at 08:00 the _main agent runs the prompt as a tracked mission — cost, tokens, duration and a full event log recorded — and Telegram pings you with the result. Swap the prompt, point it at your own agent, or fan out to several routines. Same pattern scales from a personal digest to a fleet of scheduled agents you can watch on the dashboard.

Fleet digest. Drop {{FLEET_STATS}} (or {{FLEET_STATS:30}} for a 30-day window) anywhere in a routine prompt and the scheduler expands it, at fire time, into a real activity summary from your mission history — spend, volume and failures per agent. Schedule it weekly and an agent turns those numbers into a "what your fleet did, what to look at" digest in Telegram. The stats never leave your machine; they come straight from the local DB.

Features

Agent mesh — define agents as folders (config.json + system prompt), connect sub-agents to an orchestrator, visualize the live graph.
Pluggable providers — each agent runs on the backend you choose ("provider": "claude" drives the claude CLI, "openai" drives codex exec); default is claude so existing agents are untouched. Mix providers across the fleet; add a new one with a single file.
Missions & runs — every agent invocation is a tracked mission with cost, token usage, duration and a full event log.
Channels — talk to agents from Telegram or inbound webhooks; route by @agent tag.
Routines — cron-style scheduled missions with completion notifications. No system crontab/launchd needed.
Scoped memory — per-agent notes with NONE / SESSION / USER / GLOBAL scopes, auto-injected into the system prompt. Opt-in distillation turns rolled-over transcript into a compact learnings.md, so an agent gets sharper with use instead of just accumulating logs.
Skills — reusable, filesystem-defined tools attachable to agents.
Remote access — issue scoped, expiring tokens for external agents, with rate limiting and an audit log.
Dashboards — cost trends, per-agent analytics, a Kanban board, and a real-time console.
Local-first — one SQLite database, no cloud dependency, your data on your disk.

Requirements

Node.js ≥ 20
At least one provider CLI on your PATH, authenticated once:
- claude — the default. (Claude Code, claude login)
- codex — only if you set "provider": "openai" on an agent. (OpenAI Codex CLI, codex login)
macOS or Linux (Windows via WSL — node-pty + better-sqlite3 are native).

Quick start

git clone <your-fork-url> orchestria
cd orchestria
npm install

# One-time: authenticate the Claude CLI OrchestrIA will drive
claude login

# (optional) tweak runtime config
cp .env.example .env.local

npm run dev

Open http://localhost:8000. The default _main orchestrator agent and a minimal pinger sub-agent ship ready to use.

Production build: npm run build && npm run start.

Configuration

Everything is optional — OrchestrIA boots with working defaults.

Env var	Default	Purpose
`ORCHESTRIA_SQLITE`	`.orchestria/orchestria.db`	Override the database path
`ORCHESTRIA_CHANNELS_AUTOSTART`	on	Start channel listeners at boot
`ORCHESTRIA_ROUTINES_AUTOSTART`	on	Start the routine scheduler
`ORCHESTRIA_MEMORY_AUTORECORD`	on	Record mission outputs into memory
`ORCHESTRIA_MEMORY_DISTILL`	off	Distill rolled-over memory into `learnings.md` (opt-in; uses tokens)
`ORCHESTRIA_MAX_CONCURRENT`	`8`	Max agents running at once
`ORCHESTRIA_MISSION_TIMEOUT_MS`	`1800000`	Per-mission wall-clock kill (ms)
`ORCHESTRIA_OPENAI_MODEL`	(codex default)	Model for `openai`-provider agents whose `model` is a Claude id (overrides globally)

See .env.example.

Defining an agent

Create .orchestria/agents/<id>/config.json:

{
  "id": "researcher",
  "name": "Researcher",
  "model": "claude-sonnet-4-6",
  "permissionMode": "auto",
  "allowedTools": ["Read", "WebSearch", "WebFetch"],
  "memoryScope": "USER",
  "parent": "_main"
}

Add an optional .orchestria/agents/researcher/system-prompt.md. It appears in the UI immediately — discovery is filesystem-driven, no code changes.

Provider. "provider" is optional and defaults to "claude". Set "provider": "openai" to run the agent on the codex CLI instead — leave model as a Codex id (e.g. "gpt-5-codex"), or keep a Claude model and let the codex default apply / set ORCHESTRIA_OPENAI_MODEL. An unknown value falls back to claude rather than failing the mission. You can also flip the provider from the Agents page.

Configuring a channel

Channel credentials are git-ignored. Copy the template and fill it in:

cp .orchestria/channels/telegram.json.example .orchestria/channels/telegram.json
# then add your BotFather token

Project structure

src/
  app/                Next.js App Router pages + /api route handlers
  lib/
    orchestrator/     agent spawning via node-pty; providers/ = per-agent
                      backend (claude → `claude`, openai → `codex`)
    channels/         Telegram + webhook inbound, @agent routing
    routines/         cron-style scheduler
    remote/           scoped token issuing / auth / audit
    db.ts             SQLite (better-sqlite3, WAL)
  components/         UI (visualizer, topbar, …)
.orchestria/          user-space runtime: agent / skill / channel configs
                      (databases, logs, memory, secrets are git-ignored)

Security

OrchestrIA stores agent configs in .orchestria/. Channel credentials, databases, logs, memory and *.bak files are git-ignored by design — only *.json.example channel templates are tracked. Never commit a real bot token, password, API key, third-party/client data, or a database snapshot. Authenticate each provider CLI separately (claude login / codex login); OrchestrIA never reads your key.

If you find a security issue, please open a private report rather than a public issue.

Contributing

Issues and PRs are welcome. This is an early-stage project (v0.x) — APIs and schema may change. Before touching framework code, note this repo runs Next.js 16 (breaking changes vs older majors); see CLAUDE.md.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.orchestria		.orchestria
public		public
src		src
.env.example		.env.example
.gitignore		.gitignore
.nvmrc		.nvmrc
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository files navigation

OrchestrIA — Agentic OS

Why

In practice — a daily briefing in 10 minutes

Features

Requirements

Quick start

Configuration

Defining an agent

Configuring a channel

Project structure

Security

Contributing

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

OrchestrIA — Agentic OS

Why

In practice — a daily briefing in 10 minutes

Features

Requirements

Quick start

Configuration

Defining an agent

Configuring a channel

Project structure

Security

Contributing

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages