Connect your agent

The short version

Install the plugin for your AI, press Allow in the browser once, done. On the common path there’s no token to copy and nothing to configure. The vocabulary further down this page (OAuth, bearer tokens, streamable HTTP) is for people wiring it by hand, and you can skip all of it.

tuckit publishes its board over MCP, the standard coding agents use to reach tools outside themselves. Any MCP client can talk to it, and the plugins exist to skip the wiring and teach the agent how the board is meant to be used.

Whatever you install, the agent gets the same three things:

• a note at the start of a session telling it to read live state from the board rather than from code, and to check the board before starting work;
• a reminder at the end to write decisions back, so “let’s do X next” becomes a card instead of a line in a chat log;
• the tuckit-domain skill, which is What’s on the screen in a form the agent loads on demand.

Pick your agent

Claude Code

Nothing to paste, nothing to configure.

1. In a Claude Code session:

   /plugin marketplace add tuck-it/tuckit-plugins
   /plugin install tuckit@tuckit-plugins

2. The connection ships with the plugin, so there is no separate claude mcp add. The address is prefilled to https://app.tuckit.dev/mcp. Press Enter, or type your own if you host it yourself.

3. On first use, Claude Code opens your browser to authorise once. The credential lands in your OS keychain and refreshes itself.

You also get the workflow skills, which are what the agent actually follows once it starts working. What the plugin does goes through them.

Sharing it with your team. --scope project on a plugin or server puts it in the folder’s .claude/settings.json, so everyone who opens the folder gets it. --scope local keeps it to you. Running more than one board from one machine is Running several projects. Pointing it at your own instance is Self-hosting.

If it doesn’t appear. Run /reload-plugins, then confirm with /plugin list. If you’d already run claude mcp add tuckit yourself, that manually added server takes precedence. The two don’t conflict.

Not on GitHub? /plugin marketplace add also accepts a git URL or a local path, for example /plugin marketplace add ./tuckit-plugins.

Codex CLI

1. Add the marketplace:

   codex plugin marketplace add tuck-it/tuckit-plugins

2. Install and enable it from the in-session browser:

   /plugins   →   select "tuckit"   →   install   →   enable

3. Codex doesn’t prompt during install, so give it a token through the environment variable the bundled server reads:

   export TUCKIT_MCP_TOKEN="<YOUR_TOKEN>"

   Mint the token in tuckit under Settings → Agent. Add the export to your shell profile to keep it.

This wires the primer, the reminder, the skill and the connection. No ~/.codex/config.toml edit needed. Self-hosters can point the bundled server elsewhere. See Self-hosting.

Not yet verified against a live install

The Codex plugin follows Codex’s documented hook and .mcp.json format, but it hasn’t been confirmed against a running Codex install. If the primer, the reminder, or the connection don’t come up, check your Codex version’s docs and adjust plugins/codex/hooks/hooks.json or plugins/codex/.mcp.json.

Antigravity

One command, in any shell:

agy plugin install https://github.com/tuck-it/tuckit-plugins/tree/main/plugins/antigravity

That brings the skills, the hooks and the connection. On first use Antigravity opens your browser to authorise once. There’s no token to paste.

Point at the plugin directory, not the repository

Given the repository root, agy plugin install treats plugins/ as a bulk directory and installs the Claude Code plugin alongside this one. Both are named tuckit, so they land in the same directory and their hooks.json files are merged. The merged file is then rejected whole, leaving you with no hooks at all. The /tree/main/plugins/antigravity suffix above avoids it.

Antigravity has no session-start event, so the primer rides on PreInvocation behind a first-turn guard, injecting once per session rather than every turn. Stop carries the write-back reminder, which is why the agent takes one extra turn the first time it tries to finish.

Check what you have with agy plugin list, and switch it off with agy plugin disable tuckit.

If nothing seems to happen

The install output is not evidence: it reports hooks : 2 processed for a file it hasn’t read yet. Antigravity parses hooks when the next session starts, and a file it rejects becomes a single line in ~/.gemini/antigravity-cli/log/cli-*.log. Read that log before changing anything.

agy plugin uninstall tuckit also leaves ~/.gemini/config/plugins/tuckit/ behind, so delete that directory too if you want a clean reinstall.

Connecting by hand

Skip this unless you’re wiring a client the plugins don’t cover, or running your own instance. The address is /mcp on your tuckit host:

https://app.tuckit.dev/mcp

Claude Code works out the authorisation and needs no token:

claude mcp add --transport http tuckit https://app.tuckit.dev/mcp

Codex reads a token from the environment. Add this to ~/.codex/config.toml:

[mcp_servers.tuckit]
url = "https://app.tuckit.dev/mcp"
bearer_token_env_var = "TUCKIT_MCP_TOKEN"

Antigravity also works it out, so its entry carries no token either. Put it in ~/.gemini/config/mcp_config.json to apply it to every session:

{
  "mcpServers": {
    "tuckit": { "serverUrl": "https://app.tuckit.dev/mcp" }
  }
}

Tokens are minted under Settings → Agent, where you can also disconnect any app that has authorised.

How authorisation works

Two paths, and which one you get depends on your client. In both, the agent ends up holding a credential for exactly one organisation. An agent connected to one board can’t read or write another.

Authorising in the browser is the good path, and it’s what Claude Code and Antigravity use. In plain terms: the agent sends you to a tuckit page, you pick which organisation it may act in and press Allow, and the agent receives a short-lived credential that renews itself. Nothing long-lived is ever pasted into a config file, and because the credential resolves to you, every card the agent creates records you as its author. Nothing to copy, nothing to rotate, nothing to leak in a screenshot.

You can see and revoke every agent that has authorised, at any time, under Settings → Agent.

Static tokens are the fallback for clients that can’t do this, which today means Codex. A token is a long string you generate and paste into your shell profile. Two differences worth knowing before you choose one. It belongs to the organisation rather than to a person, so writes are attributed to the org and not to you by name. And it doesn’t expire on its own, so it’s now a thing you have to keep secret and rotate yourself.

If your client supports both, take the browser path.

Check that it worked

Ask something only the board can answer:

What's the state of this project?

A connected agent reports your org, your areas, what’s finished, and how many items are sitting in the Inbox. One that answers by reading files or commit history isn’t connected. That’s the tell.

Next: The daily loop.