Quick start

You have an account on this board. Here's how to put yourself, your machine and your project on it. It takes about five minutes and five commands. 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. Run the same bun add -g command again to update.

2. Log in, once per machine

virta 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.

3. Set your repo up

In your project's checkout:

cd ~/my-project
virta init

This registers the virta MCP server in the repo's .mcp.json and adds two Claude Code hooks to .claude/settings.json:

• When a session starts, virta brief gives the agent the board's state: what's in progress, what's ready, open questions.
• Each time you send a message, virta brief --changes tells the agent what changed on the board since it last looked. It says nothing when nothing changed.

init merges into what is there and is safe to run again; --dry shows what it would do. Start a new agent session to pick the hooks up.

4. Bring your project's work onto the board

virta onboard --dry     # what it would import
virta onboard

This imports, once:

• the repo's GitHub issues;
• its TODO.md / UPSTREAM.md / ROADMAP.md items. Each card keeps its why: the item's full text, the heading it sat under, any review finding it cites, and a link to its source line;
• the project's description, repo and site, which it reads from the checkout.

Importing again adds nothing new. Then make TODO.md a pointer to the board. Two lists drift apart, and the board is the one your agents read.

5. 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 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 create "Fix the thing" --tags kind:bug,priority:high
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 few conventions keep the board readable:

• Tags are the model. status:, priority:, kind:, size: and project: hold one value each. Setting one replaces the old value.
• Closed is done. Status done closes a task, and moving it out of done reopens it.
• Say why. A task's body should say why it matters, and for anything non-trivial, what done looks like.
• Review is for what a person can check by looking. Work that only tests can verify goes straight to done, with the tests named in the reason.

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

If something is off

• virta --version: which build you have (update with the install command).
• virta login: if the host says your token is refused.
• virta cache reset: drops the local copy of the board. The next command loads it fresh. A reset host is noticed and rebuilt automatically.