Quick start

You have an account on this board. Here's how to put yourself, your machine and your project on it. It takes a few minutes and a handful of commands, plus a triage of what your project brings with it. Everything below runs in a terminal.

1. Install virta

virta runs on Bun. If you don't have it: curl -fsSL https://bun.sh/install | bash. Then install the CLI and the MCP server straight from this site:

bun add -g https://virta.tosijs.net/virta.tgz
virta --version

virta --version names the build you have. To update, run virta update. It installs the site's latest build. Re-running the bun add -g line above won't update: bun caches a tarball by its URL and keeps the copy it has.

2. Log in, once per machine

virta self login

This opens your browser. Approve the request with your account, and the CLI keeps a token for this machine in ~/local-secrets (mode 0600). Everything you write is attributed to you by the host.

Approved, but the terminal keeps waiting? After you approve, the page hands the token back to a small listener virta runs on 127.0.0.1. A VPN, a managed browser or security software can block that. Press Ctrl-C and run virta self login --poll instead: the CLI asks the host until the approval is there, and nothing needs to reach your machine. Only approve a link you generated yourself.

3. Set your repo up and bring its work over

This is the one step you run yourself, or approve (board #3618). It gives your agent hooks that run at every session start and every prompt, and it writes your project's work to the shared board. An agent in a permission-gated mode is refused it, and rightly so. Let it run the --dry preview and show you the output, then run the real command yourself (in Claude Code, type ! virta project setup).

In your project's checkout:

cd ~/my-project
virta project setup --dry   # what it would write and import, nothing written
virta project setup         # the same preview, one yes, then both

It does two things behind one preview and one yes:

Both merge into what is there and are safe to run again. When it has written the hooks, it ends by asking you to restart the session so they load. The two halves still run on their own: virta project init and virta project onboard, each with --dry.

4. What onboarding brings over

virta project onboard --dry --verbose  # every title it would import
virta project onboard --skip UPSTREAM.md  # leave a record file out (setup takes it too)

The dry run counts, for each source, the tasks it would create, how many arrive closed, and how many are already on the board. A long-lived TODO.md can hold hundreds of items, so read it before you go ahead.

Run in your repo's checkout, virta project onboard also enrolls the project: from then on, its brief speaks in your agents' sessions. Only a repo can enroll itself. Tasks others file against it are visible on the board but change nothing until you onboard.

Onboarding imports, once:

Importing again adds nothing new.

Your project's page

Onboarding fills in what the checkout says: the description (from package.json or the README), the repo (from the git remote) and the site (the package's homepage). The package and version follow from the repo. Check what it found, and fill in the rest:

virta project show my-project                # what the board knows
virta project set my-project --site https://my-project.dev
virta project set my-project --icon 🧭 --color teal
virta project set my-project --repo owner/my-project --description "One line on what it is"

Only the settings you give change. On the board, the gear on a project's tile opens the same settings.

5. Triage what arrived

An import is a first draft of your backlog, not the backlog. Do this in the repo's own agent session, which knows the history:

Then make TODO.md a pointer to the board, in prose, with no list items (a list item there would be imported as a task). Two lists drift apart, and the board is the one your agents read.

6. Open your board

https://virta.tosijs.net/host/#?virta.scope=<your-project>

Sign in, and your project's lanes are there: inbox, backlog, ready, in progress, review, done. Drag cards between them, or use a card's status menu.

Working from the board

The shell is the API, for you and for agents:

virta project brief                                      # what's new, in progress and ready here
virta ls "status:ready"                                  # a filter: tags, #numbers, ~text
virta show #42                                           # one task: body, tags, recent comments
virta new "Fix the thing" --tags kind:bug,priority:high  # this repo's project
virta work #42                                           # pick it up: in progress, and you're on it
virta review #42 "check the lanes on a phone"            # finished; a person should look
virta done #42 "shipped in 1.2.0"                        # finished; nothing to check

A task you create in an enrolled repo belongs to that repo's project unless you pass --project (the repo is named by its git remote, so a checkout under another directory name still counts). Created anywhere else with no project, it is on no board, and create says so.

A few conventions keep the board readable:

For agents has the full picture: every verb, MCP, the tag conventions, and how a project adopts the board.

If something is off