User manual

One command, and your team is working.

Connect GitLab, add a project, type owenagents. This page shows what happens next, the few commands you use every day, and how to work with the agents.

I code with

commands below follow your choice · select any text for quick actions

Start here

Quick start

Four steps, about three minutes. Tick them as you go — this page remembers.

0/4

Sign in and connect GitLab
Google, GitHub or GitLab to sign in; then GitLab by OAuth, so the agents can read and move your board.
Open Setup
Add a project
Pick one of your GitLab projects or create one. Choose Auto or Review before ship — you can change it later.
Open Projects
Install the CLI
Node 20 or later. One file from the latest release, no other dependency. The same URL always gives the newest version: run it again to update.
```
npm install -g https://gitlab.com/owenagents/owenagents-cli/-/releases/permalink/latest/downloads/owenagents-cli.tgz
```
Type owenagents
It signs this machine in, installs the plugin in your tool, clones the project, sets it up and starts the team.
```
owenagents
```

Under the hood

What happens when you type owenagents

Only what is missing: the first time it signs in and installs the plugin; afterwards it goes straight to the team.

first run, illustrated — your output names your account and project

$ owenagents
Welcome to Owen Agents — first, this machine
✓ server Owen Agents — API v1
Sign in in your browser — check that the page shows the code  KQ7M-2PXD
✓ logged in as you — license key saved in ~/.config/owen/owen.env
Owen plugin
✓ Claude Code plugin installed
Setting up Owen in ~/owenagents/app
✓ launcher .owen/bin/owen
✓ config .owen/config.json (acme/app, reviewer you)
board ready: https://gitlab.com/acme/app/-/boards
✓ git HTTPS credentials for gitlab.com from Owen Agents
Owen starts on acme/app with Claude Code
== owen-rm   nothing validated to merge
== owen-qa   #12 — 4/4 criteria pass, report written → rm
== owen-dev  #14 — MR !31 opened, 6 tests, typecheck ok → qa
== owen-pm   #15 written with its spec → dev
pm 1  →  dev 1  →  qa 1  →  rm 1

Nothing secret lands in your repository. The license key is in ~/.config/owen/owen.env; GitLab and Slack tokens are fetched short-lived at each turn.
Each agent works in its own folder, .owen/work/, never in your checkout.
OWEN.md, the team's playbook, is filled from your repository the first time. Read it, fix it, commit it.

The loop

How the team works

Each ticket moves through four columns of your GitLab board. The agent who owns a column is the only one who acts on it, and agents talk only through notes on the ticket — everything is visible in GitLab.

Chosen per project, in your dashboard.

owen-ux · draws the screens before dev codes
owen-cto · settles every disagreement
owen-em · watches the flow, runs retros

An ideayours, or a bug QA found
owen-pmwrites the spec#41
owen-devbuilds it
owen-qaproves itfails → back to owen-dev
owen-rmre-verifies
Shippedv0.4.0 + notes

GitLab, the shared memory — every hand-off is a note on the ticket.

Slack, your line — only what needs a human.

Auto: the team ships on its own.

owen-qa validates every criterion, owen-rm re-verifies and merges.
Release notes are published; you read the result in GitLab.
Slack only when a human must act: money, access, a secret.

owen-pm — Searches for duplicates, writes Given / When / Then criteria against the code on main, opens the ticket's branch with its spec. Never guesses a criterion; creates nothing while the board is full.

your partOpen an issue with owen:loop and owen:pm — or let it propose.

Three more agents have no column: owen-cto arbitrates disputes and blocked tickets (it runs with owenagents start --interactive), owen-em runs retrospectives, owen-ux designs screens before development.

Commands

I want to…

Pick what you want to do; copy the command.

Project (optional)

owenagents

Sets up what is missing, then runs a round every 15 minutes: rm → qa → dev → pm. Ctrl-C stops it; the tickets stay where they are.

Cheat sheet

Every day

owenagents

Start the team again — last project and tool remembered.

owenagents board

pm 1 → dev 2 → qa 0 → rm 1, blocked apart.

owenagents logs

What each agent did today. Add a role, or -f to follow.

owenagents open board

The GitLab board in your browser.

Stop the team with Ctrl-C. Nothing is lost: tickets stay in their column and the next start picks them up.

Collaboration

Working with the team

Give it work

Open an issue with the labels owen:loop and owen:pm. owen-pm turns it into a ready ticket. Without input, it proposes features itself — one per round, none while 5 are open.

Answer a question

Agents address you in a note on the ticket, or on Slack. Reply there; the next turn reads it.

Pause a ticket

Add owen:blocked; remove it to resume.

Take a ticket back

Remove owen:loop: the agents stop touching it.

Keep the Commands section of OWEN.md real — install, tests, typecheck, audit: dev and QA run them and paste their actual output.

Messaging

Talking with the agents on Slack

With Slack connected, agents post in your private #owen-agents channel under their own names — one thread per ticket, release or retrospective.

Answer in the thread; the agent reads it at its next turn and replies there.
Only authorized people are listened to: whoever installed the app, plus the ids in slack.authorized.
They write when a decision is yours, when something ships, and when something breaks — not for every step.

Control

Auto, or review before ship

QA validates
owen-rm re-checks
merged
released

Validated work ships without waiting. Good for a side project, or once you trust the team. Set per project in Projects.

Claude Code

Inside your coding tool

The CLI runs everything for you. Inside the tool, the same team answers these commands.

/owenagents:login
/owenagents:status
/owenagents:init
/owenagents:tick
/owenagents:cto

Each role runs as claude -p --agent owenagents:owen-<role>; /loop /owenagents:cto runs the orchestrator.

Update the plugin

claude plugin update owenagents@owenagents

Settings

Project configuration

.owen/config.json is written at setup; shared settings come from your dashboard. Commit it with OWEN.md so the whole team shares them.

Key	Default	Meaning
`release.ship_mode`	auto	auto or review — see Ship mode. Set from the dashboard.
`release.reviewers`	[]	GitLab usernames whose approval also ships, besides you.
`release.min_tickets`	1	Merged tickets needed before a release.
`wip.max_open_before_pm_creates`	5	owen-pm creates nothing while this many tickets are open.
`wip.max_new_tickets_per_tick`	1	New tickets per round, at most.
`wip.max_qa_rounds`	3	QA rejections before owen-cto arbitrates.
`parallel.dev / qa / pm`	1	Agents of a role working at the same time.
`pm_lenses`	user, market	How owen-pm looks for features.
`loop.sleep_seconds`	900	Pause between rounds.
`loop.agent_cmd`	per tool	Written by owenagents start for the tool you chose.
`slack.authorized`	the installer	Slack ids the agents listen to.
`gitlab.project / reviewer`	set at setup	The project, and you as its reviewer.

Security

Installs, keys and revoking

Installs lists every machine and tool signed in — version, last seen, last project — and your connections. Revoke one: it stops at its next turn.
Install & keys makes a key by hand for a CI runner or server: OWEN_CLOUD_URL and OWEN_LICENSE_KEY in ~/.config/owen/owen.env, chmod 600.
Disconnecting GitLab stops every agent at its next turn.

Help

Troubleshooting

First reflex: owenagents check

license key rejected / 401+
The key was revoked in Installs, or belongs to another server.
```
owenagents init --relogin
```
GitLab is not connected for the agents+
Connect GitLab in step 1 of Setup.
```
owenagents open setup
```
no project configured+
Add a project in the dashboard, then run owenagents again.
```
owenagents open projects
```
Owen plugin not installed for a tool+
Replace codex by claude or agy. Several GitLab accounts? Add --git-base git@<ssh-alias>:owenagents.
```
owenagents init --tools codex
```
git asks for a password on clone or push+
Starting again sets git's credentials for the project's host, from Owen Agents.
```
owenagents
```
an agent does nothing+
“nothing to do” means its column and inbox are empty: give owen-pm work, or wait for the next round.
```
owenagents logs dev
```
self-signed certificate / unable to verify+
For a self-hosted Owen Agents server.
```
owenagents init --ca-file path/to/ca.pem
```
plugin behaves like an older version+
Update the plugin in your tool (see the tool picker above), then restart the tool.
```
claude plugin update owenagents@owenagents
```
several projects here — name one+
logs and board use the last project started; name another with -p or as an argument.
```
owenagents logs -p owner/project
```

Everything

Reference

owenagents — every command and option

owenagents                                   set up what is missing, then start
owen …                                       the same command, shorter (owen board, owen logs…)
owenagents start [project] [--tool claude|codex|agy] [--once] [--interactive] [--dir PATH]
owenagents logs [role] [-f] [-p project] [-n lines]
owenagents board [project]
owenagents open [board|dashboard|projects|installs|setup|docs]
owenagents init [--relogin] [--tools claude,codex,agy] [--yes] [--git-base GIT] [--host URL] [--ca-file PEM] [--no-plugins]
owenagents check
owenagents version

.owen/bin/owen — in your repository

owen status            account, plan, connections
owen board             tickets per column
owen queue <role>      a role's tickets, oldest first
owen show <iid>        a ticket and its whole thread
owen inbox <role>      unread notes addressed to a role
owen pull              shared config from Owen Agents
owen setup             labels and the "Owen" board
owen loop [--once]     the loop, without the CLI