atris

# atris **atris**: you say what you want in plain words. atris builds it, checks it, and shows you proof. Under the hood it is an operating system for AI work. It turns any repo into a workspace an agent can actually operate: shared context it reads before it acts, a `plan -> do -> review` loop, durable tasks and daily logs, and verification that ends work on a real check instead of a promise. Every owner gets persistent computers to run it: ```text Owner = User | Business Owner has many Computers Computer = workspace + files + tools + secrets + memory + agents + validation loop ``` A computer can be personal or shared by a business. It can run a job like code, research, CRM, reporting, event ops, support, or business ops. ## Quick Start ```bash npm install -g atris cd your-project atris init && atris ``` ## For Coding Agents **Read [`FOR_AGENTS.md`](FOR_AGENTS.md) first**: why agents adopt Atris, 60-second start, spread-it instructions. If you're an agent, run: ```bash atris ``` Then read the workspace's `atris/atris.md` and follow it exactly. `atris.md` is the source of truth. --- ## What Atris Gives You - An AI workspace on top of any repo - Persistent AI computers for scoped jobs - A local computer card that makes each workspace inspectable - A strict `plan -> do -> review` loop - Daily logs, task tracking, feature packs, and project memory - Skills, team members, integrations, and cloud sync when you need them - A plain answer to "what did my AI actually do?": run `atris recap`, or `atris recap --share` for a receipt-backed summary you can paste anywhere ## Critical Files | File | Purpose | |------|---------| | `atris/atris.md` | Main instructions for agents working in this repo | | `atris/MAP.md` | Navigation index with file:line refs | | `atris/TODO.md` | Human-readable task view | | `atris/logs/YYYY/YYYY-MM-DD.md` | Daily log, inbox, notes, completions | | `atris/features/` | Feature packs with `idea.md`, `build.md`, `validate.md` | | `atris/skills/` | Reusable skills for agents | | `atris/team/` | Team member specs and local context | | `atris/wiki/` | Repo memory, briefs, concepts, and wiki health | ```text atris/ ├── atris.md ├── MAP.md ├── TODO.md ├── logs/ ├── features/ ├── skills/ ├── team/ └── wiki/ ``` ## Install ```bash npm install -g atris atris --version ``` Requires Node.js 18+. `atris task` uses built-in SQLite and requires Node.js 22+. If you want Atris cloud workspaces, businesses, or integrations, run `atris setup` after install. ## How To Run Atris ```bash cd your-project atris init atris ``` `atris init` scaffolds the workspace, including `atris/wiki/`. `atris` loads context and hands the workflow off to `atris/atris.md`. If you're still shaping the idea, use `atris brainstorm`. If you want Atris to finish one job and prove it worked, use `atris run "<objective>"`. If you want Atris to keep picking the next mission or member until you say stop, use `atris autopilot`. If you want project memory checked for stale pages and missing context, use `atris loop`. `atris activate` surfaces wiki state from `atris/wiki/STATUS.md` when it exists. Core loop: `plan` -> `do` -> `review` Integrates with any agent. ### Publish a static site Upload any built static site to an Atris-hosted subdomain. See [docs/site-publish.md](docs/site-publish.md) for flags, limits, profiles, and troubleshooting. ```bash atris site publish dist --slug my-site --spa atris site publish . --slug my-next-app --profile app --build # Next.js static export ``` ### Bring people together with the Host The Host is a team member that gets to know everyone in a room (a company, a club, your own network) through one fun question at a time, keeps a card for each person, and introduces two people only when both say yes. Then it offers to find a time and checks that it happened. It never reads anyone's messages and keeps no scores. ```bash atris member install host atris host setup --room personal # your own network: it asks you, and drafts messages for you to send atris host import people.jsonl # bulk add people and who already knows whom atris host room # the host's weekly read ``` ### Put members to work Members are helpers that work in their own copy of the repo. Three words cover it. Run hands over one job. Atris picks the right member and starts it. ```bash atris member run "fix one failing test" ``` Wake keeps members working, each one pulling the next task that fits. Give a number, or name the members you want. ```bash atris member wake 5 atris member wake navigator executor ``` Wake only picks jobs that have a test to pass, so members know when they are done. Add one like this: ```bash atris task new "fix the flaky login test" --verify "node --test test/login.test.js" ``` Each job gets the time limit set for building in your roster, plus a few minutes for review. To see or change it: ```bash atris engine roster ``` Naming just one member runs one step of work. Add `--keep` to keep that one member working. ```bash atris member wake executor --keep ``` Sleep stops the members that are awake. ```bash atris member sleep --all ``` To watch them, open the board, or follow one member's steps as they happen. ```bash atris member board --watch tail -f ~/.atris/progress/executor.log ``` When a member finishes, ask for its result: what it changed, its receipt, and one number. Each member's copy of the repo stays until its work lands, then tidy puts it away. ```bash atris member result executor atris member tidy --dry-run ``` The older words still work as aliases: `dispatch` and `go` do what run does, and `up` does what wake does. ### How member work gets checked and lands Every member job ends with its own check, a command that must pass. Then a second engine reviews the change, and it is never the engine that did the work. Work lands on its own only after you switch self-landing on, once. From then on Atris pushes the branch, opens a pull request, and turns on GitHub auto-merge, so GitHub merges it when the branch is up to date and CI passes. ```bash atris autoland on ``` Anything else keeps the work on its branch, with one plain line saying why. That covers a failed check or review, unsaved changes, a clash with the main branch, and work that touches a protected area like payments, deploys, or credentials. A job that fails three times in a row stops and waits for a person. ## Chat With Atris 2 `ax` is the Atris 2 chat and coding-agent CLI. It uses the hosted Atris cloud by default, streams text, shows tool activity, and keeps fresh installs away from local setup. ```bash cd your-project ax chat ax --fast ax --fast "hello" ax --pro "help me plan this task" ax --max "reason through this hard decision" ax --doctor ``` Use Fast for quick chat and low-latency Atris loops. Use Pro for deeper tool loops. Use Max for the hardest jobs; it runs the highest-reasoning model and takes longer per turn. Advanced local workspace mode is opt-in with `--local` plus `AX_BACKEND_URL`. ## Play AgentXP AgentXP is the proof-backed game loop for getting better with agents. Start it inside any project folder: ```bash npm exec --yes --package atris@latest -- atris play ``` The first run creates a local starter mission if one does not exist. The loop is: ```text start -> proof -> accept -> login -> sync ``` The player path: ```bash atris play atris task claim <mission-ref> --as game-manager atris task ready <mission-ref> --as game-manager --proof "<artifact path + verifier result>" atris task accept <mission-ref> --as justin --proof "<human review>" atris xp card --local atris login atris xp sync --local ``` The manager path: ```bash atris gm --player justin ``` No proof, no AgentXP. `atris task done --proof` records review/RL context, but only human `atris task accept` mints Career XP for the local card or hosted leaderboard. ## Agents That Sign In On Their Own `atris login` signs a person in. An agent can sign itself in with an agent client, so no one has to hand it a login token. The owner makes the client once. The secret is shown one time, or written to a private file with `--secret-file`: ```bash atris agent-client create --name nightly-bot --scopes mcp:read,x-search --secret-file ./bot.secret atris agent-client list atris agent-client rotate <client_id> atris agent-client revoke <client_id> ``` The agent signs in with the id and the secret file. Its short token renews on its own; the secret and token are never printed: ```bash atris login --client-id atc_... --client-secret-file ./bot.secret ``` Or set `ATRIS_CLIENT_ID` plus `ATRIS_CLIENT_SECRET_FILE` (or `ATRIS_CLIENT_SECRET`) and run `atris login` once. It reads them, no flags needed, and opens no browser. After that every command renews the token on its own. `ATRIS_TOKEN`, when set, still wins. ## Business Owners If you want a shared owner for a company, lab, collective, community, artist, team, or project, use the business command instead of raw `atris init`. ```bash atris business init "Example Co" --owner-email operator@example.com cd ~/arena/atris-business/example-co atris business onboard --website https://example.com --contact "Example Owner" --note "sample customer workspace" atris align --fix ``` That creates the shared owner, creates its first/default computer, writes `.atris/business.json`, initializes `.atris/state/` for events and run history, and scaffolds the local `atris/` workspace under `~/arena/atris-business/<slug>/` with starter roles, a default recap template, and an initial task queue in `atris/TODO.md`. If you do not have a neat source pack yet, `atris business onboard` is the easiest intake step: give it a website, a named human, a few notes, or run it in a folder with loose files. Atris turns that into raw intake, a starter brief, a first workflow, a safe next action, and a short operator brief. Use the owner's language when you talk about it: ```text Your business runs on Atris. Your lab runs on Atris. Your collective runs on Atris. ``` You can also use bare input: ```bash atris business onboard https://example.com "founder-led b2b ops" ./notes.md ``` If you already have a folder full of source material, run it from there with `atris business init "Example Co" --here`. When the first recap is done, record it into the RL state logs: ```bash atris business record atris/reports/2026-04-12-operator-recap.md --outcome mixed --metric "operator speed" ``` ## Core Commands | Command | Purpose | |---------|---------| | `atris` | Load context and start | | `atris init` | Scaffold an Atris workspace | | `atris brainstorm` | Explore before planning | | `atris plan` | Create the plan/spec | | `atris do` | Execute work | | `atris review` | Validate work and capture learnings | | `atris run` | One bounded mission pursuit: start or resume, tick, complete (`--legacy` for the old plan/do/review chain) | | `atris run logs` | Browse glass run logs (phase reasoning persisted to disk) | | `atris run prune-logs` | Prune old run logs, keeping only the most recent N | | `atris run search` | Search phase reasoning across all run logs by keyword | | `atris run stats` | Show run log stats: phase counts, avg durations | | `atris run export` | Export all run logs as a JSON bundle | | `atris run diff` | Compare two run logs side by side | | `atris autopilot` | Keep the workspace moving: mission/member legs until `atris autopilot stop` (`--legacy` for the old approval loop) | | `atris pulse` | Install or run the durable overnight heartbeat | | `atris log "note"` | Add an inbox item to today's journal (`log --repl` for the editor; `wish` for headless intake) | | `atris now` | Show the current operating truth | | `atris radar` | Show live agents joined with tasks, missions, and worktrees | | `atris ctop` | Show process-first live agent CPU and memory | | `atris status` | Show active work and completions | | `atris task` | Durable local task state and the agent work loop | | `atris mission` | Durable goal, owner, verifier, tick receipts, and loop state | | `atris play` | Enter the AgentXP player loop for one proof-backed mission | | `atris gm` | Enter AgentXP General Manager mode for player missions and review queues | | `atris xp` | Show the local AgentXP card and sync eligible proof to the hosted leaderboard | | `atris codex-goal` | Inspect native Codex task goals and keep completed tasks closed | | `atris learn` | Manage structured learnings | | `atris ingest` | Stage raw evidence into `atris/context/` and compile into `atris/wiki/` | | `atris loop` | Refresh wiki health, stale/orphan signals, and next ingest candidates | | `atris wiki` | Full wiki namespace: ingest, query, lint, search, log, and loop | | `atris receipt` | Save evidence from an agent run | | `atris experiments` | Run small experiments and compare results | | `atris computer card` | Show or write the local owner/computer card | | `atris release` | Draft or publish a version bump, tag, GitHub release, and launch post | | `atris slop` | Deterministic slop detector: frontend/prose tells, plus `slop dead --exports` for dead code | | `atris clean` | Housekeeping: heal MAP refs, archive journals, report stale pages and dead code | ### Doctor `atris doctor [--json]` checks Node, task support, authentication, and workspace readiness. ### Document health `atris doc-health [--json] [--questions <path>]` scores document size, map coverage, lookup hops, and feature/member freshness from 0 to 100, and lists similar feature names. Tokens are estimated as characters divided by four. Boot load earns all 20 points at or below 80,000 characters, falls linearly to zero at 200,000, and stays at zero above that. Questions default to `atris/doc-health/questions.jsonl`, one `{"q":"where is the CLI router","expect":"bin/atris.js"}` per line. Custom paths are relative to the workspace root. Missing questions skip lookup scoring and contribute zero of its 30 points. Member age uses the newest log file's modification time. ## Built-In Systems - `atris learn` stores structured project memory in `atris/learnings.jsonl` - `atris wiki` keeps repo memory in `atris/wiki/` by default, with `--cloud` when you want the remote workspace path - `atris ingest` now stages local source packs under `atris/context/_ingest/`, writes a manifest receipt, and refreshes `atris/wiki/STATUS.md` plus `log.md` - `atris wiki --private` stores local-only sensitive notes under `.atris/presidio/` - `atris loop` refreshes `atris/wiki/STATUS.md` and `atris/wiki/log.md`, flags stale/orphan pages, and suggests the next ingest - `atris activate` loads the current wiki status so the next session starts with project memory, not just tasks - `atris member` keeps team-member identity and learning local-first: `MEMBER.md` is the role contract, `goals.json` is the machine-readable goal/experiment state, `goals.md` is the human readout, and `logs/YYYY-MM-DD.md` records what happened. Use `atris member goal`, `tick`, `status`, `block`, and `review <name> <experiment-id> --accept --proof "..." --value 1..5` to test whether a member is making useful progress or needs the operator/orchestrator. - `atris codex-goal` is the read-only bridge for native Codex `/goal`: `status` inspects the live goal database, while the legacy `reset` command now refuses every mutation. Active tasks continue in place; completed tasks retain their final goal, and new work or recurring monitors use a new dedicated Codex task. - `atris task` keeps durable local task state and append-only events for agents; `atris/TODO.md` is just a regenerated readable board. Run the loop with `atris task new`, `delegate "..." --to <owner>`, `next`, `say`, and `ready <id> --proof "..."`; human approval is `atris task accept <id>` (moves to Done, awards Career XP) or `revise <id> --note "..."`. Final task transitions also append the general daily log and, when a real `atris/team/<member>/MEMBER.md` matches the task owner, that member's daily log. Add `--json` for headless agents, `atris task serve` for the local board, and `atris task show <ref>` / `events --all` for the full ledger. Commands accept semantic refs (`OBL-18`), full IDs, or any unique prefix. In cloud business workspaces, Supabase `tasks` is the source of truth and Swarlo the live claim layer. - `atris mission` is the durable autonomy layer: start with an owner, verifier, runner, and stop condition; record bounded work with `mission tick`; close with `mission complete` only after proof. Runners include `manual`, `claude`, `atris2`, and `codex_goal`. - `atris pulse` is the OS-cron heartbeat for overnight self-improvement. Use `atris pulse status`, `tick`, `run`, `install --cadence "<cron>" --days 7 --verify "npm test" --model claude-opus-5-5`, and `uninstall`. - `atris experiments` runs small test packs in `atris/experiments/` - `atris pull` and `atris push` sync cloud workspaces and journals - `atris live` keeps a business brain fresh by checking/fixing the workspace, pushing local state, pulling cloud state, and pushing again after local changes go quiet ## Engines An engine is the intelligence that builds a mission. Every installed headless coding CLI is a swappable worker behind one contract: a bounded prompt goes in, verified proof comes out, and engines never self-certify their own work. The house default is `atris-fast` (`ax`); `claude`, `codex`, `cursor`, `devin`, `grok`, and others join when their CLIs are installed. ### Who does each job `ROSTER.md` says which tool and model does each job. Edit it any time; every project, team member, and new chat follows it. ```markdown ## build - claude code, model: opus 5.5 ## review - codex, model: gpt-6-astra, effort: medium, max: 20 min, prep: search - claude code, model: opus 5.5 ``` The first ready worker leads and the rest are backups. `~/.atris/ROSTER.md` covers every project on the machine; `atris/ROSTER.md` overrides it for one project. A worker that stalls sits out 30 minutes and the next one takes over. The roster warns when a worker runs an old model and a newer one in the same family is on this machine, and prints the command that moves it. It also warns when a pinned model has no proof in 30 days. A landed run is proof; so is `verified 2026-09-30` on the line after a quick smoke test. ```bash atris engine roster # who does what, with each worker's recent record atris engine assign build claude --model "opus 5.5" # change a job's lead atris engine roster --available # tools and models on this machine atris team # who really worked in the last 7 days, then quiet and idle atris team --record # also save one row per member per day for the learning loop ``` Show every installed engine and the current default: ```bash atris engine ``` Flip the default for this workspace (persists to `.atris/engine.json`): ```bash atris engine cursor atris engine reset # back to the house default (atris-fast) ``` Ride a different engine for one run only, without changing the default. `--engine <name>` works on `mission run`, `autopilot`, and `run`. Per-run flags and `ATRIS_RUNNER_PROFILE` always beat the saved file. ```bash atris mission run "fix the flaky login test" --engine codex ``` ### Fleet Flight `atris mission run --fleet` staffs every idle installed engine on the board's claimable safe-lane tasks: one mission per task, one worktree per engine. Builds run in parallel; arrivals land serially with rebase-before-ship, so a rebase conflict pauses that landing (never auto-resolved) and keeps its worktree instead of orphaning work. Each flight writes a receipt to `atris/runs/fleet-<stamp>.json`. ```bash atris mission run --fleet --slots 3 # staff up to 3 engines atris mission run --fleet --dry-run # preview the staffing only ``` ## Verifiable Feedback Loop Under the hood, Atris can keep score on real repo work. - Tasks can carry a `Verify:` command, so work can end on a deterministic check instead of pure prose. - Plan, do, and review now carry the same Confidence Gate: find every plausible loophole, patch it with source/proof/verifier/owner/rollback, or name it as residual risk before advancing. - `atris autopilot` can run that check after review and record the result in the journal. - Future task picks can use recent results, so Atris learns from repo-local history without claiming model retraining. ## Benchmark Harness Atris ships one public head-to-head benchmark harness for comparing a pinned single-model baseline against a coordinated stack run on the same task brief. Quickstart: ```bash node bin/atris.js experiments validate endstate-baseline node bin/atris.js experiments validate endstate-stack node bin/atris.js experiments run endstate-baseline --dry-run node bin/atris.js experiments run endstate-stack --dry-run node bin/atris.js experiments compare endstate ``` One-command rehearsal: ```bash node bin/atris.js experiments replay endstate ``` What to inspect: - receipts land in `atris/experiments/endstate-baseline/artifacts/` and `atris/experiments/endstate-stack/artifacts/` - scores append to each pack's `results.tsv` - `atris experiments compare endstate` prints the latest side-by-side comparison - `atris experiments replay endstate` runs the full public dry-run rehearsal - the benchmark contract lives at `atris/features/endstate/contract.md` - the verification log lives at `atris/features/endstate/validate.md` The stack wins Level 1 only if it beats the baseline on total score and does not lose the reviewed completion category. ## Skills Atris ships a real skill catalog in `atris/skills/`, not just one workflow file. Examples: - `atris`, `autopilot`, `autoresearch`, `wiki`, `loop` - `backend`, `design`, `copy-editor`, `meta`, `writing` - `github`, `email-agent`, `calendar`, `drive`, `slack`, `notion`, `slides`, `x-search`, `youtube`, `ramp` - `apps`, `create-app`, `create-member`, `memory`, `magic-inbox`, `improve`, `skill-improver`, `flow` ```bash atris skill list atris skill audit [name] atris skill fix [name] atris skill create <name> atris skill link [--all] ``` For Codex, copy any skill folder into `~/.codex/skills/`. ## Before a New Version Run the release-facing checks before bumping: ```bash node bin/atris.js --help node bin/atris.js pulse --help node bin/atris.js release --help node --test ``` Then dry-run the release: ```bash atris release --dry-run ``` `atris release` drafts or publishes from local git history. `--dry-run` prints the planned bump without committing, tagging, or pushing. ## Update ```bash atris upgrade # Install latest from npm atris update # Sync local workspace files to new version ``` Packaged npm installs check for new versions during normal commands and start a background update automatically. Git checkout installs stay manual so linked development copies are not overwritten unexpectedly. --- **License:** MIT | **Repo:** [github.com/atrislabs/atris](https://github.com/atrislabs/atris.git)