Skip to content
YokkaDocs

Quickstart

  1. Create a workspace. Sign up. Your first sign-in creates a workspace with a project from the Agent kanban template: a Features swimlane and a Bugs swimlane with sensible flow rules, a “Say hello from your agent” card to test with, and a few sample cards on planning, shaping the board and checking fixes. Your first workspace also gets 3 days of Pro, no card needed (see Plans). There’s no template to pick now; you pick one when you create another project. Joining from an invitation instead? You land in that workspace and on the same connect screen, so you can connect your own agent.

  2. Pick your app. The connect screen asks which app you use and shows only that app’s steps, with your workspace token filled in. Claude Code installs the Yokka plugin with the token, and Codex reads it from an environment variable. Every other client connects through the token’s private link:

    https://api.yokka.ai/mcp/c/<token>

    The link contains the token, so treat both like a password.

  3. Connect your agent. The connection is called yokka. If you belong to several workspaces, each gets its own, named yokka-<workspace> (Yokka <workspace name> in the chat apps), so they don’t collide. The connect screen shows the name to use.

    Install the Yokka plugin. It adds the connection, skills for the card work loop, commands like /yokka:next and /yokka:plan, and a check before each turn ends:

    Terminal window
    claude plugin marketplace add yokka-ai/plugins
    claude plugin install yokka@yokka --config token=<token>

    The connect screen shows both commands with your token filled in. The plugin connects one workspace; if you’re in several, add the others with the command below and the name the connect screen shows.

    Or add the connection on its own, without the plugin:

    Terminal window
    claude mcp add --transport http --scope user yokka <link>

    If you added a yokka server before, the command fails because the name is taken. Remove the old one first, then add it again:

    Terminal window
    claude mcp remove --scope user yokka

    Without the plugin, you can still have Claude Code check the board before each turn ends, so it never stops with a card left in progress and nothing said about it. Add this Stop hook to ~/.claude/settings.json (use your connection’s name as server), or copy the prompt from the connect screen and Claude Code adds it for you:

    {
      "hooks": {
        "Stop": [
          {
            "hooks": [
              {
                "type": "mcp_tool",
                "server": "yokka",
                "tool": "stop_check",
                "input": { "stop_hook_active": "${stop_hook_active}" },
                "timeout": 30
              }
            ]
          }
        ]
      }
    }

    See before you end your turn for what it checks.

  4. Say hello, and set up the repo. The connect screen walks you through three steps: Connect, Set up your repo and Bring your work. Each one can be skipped. Once your agent connects, ask it to pick up Say hello from your agent (the connect screen gives you the exact message). The card’s brief has your agent report progress once and, when it’s working in a code repo, add the section below to AGENTS.md or CLAUDE.md. The screen ticks Set up your repo as soon as the card is done. In the Claude app or ChatGPT there’s no repo, so the step is just the first card.

  5. About repo instructions. Every agent already gets Yokka’s instructions when it connects: track the work you ask for as cards, claim before starting, wrap up before stopping. What the server can’t know is which project a repo belongs to, so the repo instructions, a short section in AGENTS.md or CLAUDE.md, name it. They never contain your token, so they’re safe to commit. To set up another repo, or to do it yourself, use Copy setup prompt on the connect screen (under Rather set up the repo yourself?) or in Project settings → Prompts → Repo instructions, where you can also copy the section to paste by hand. With the Yokka plugin, /yokka:setup-repo adds it too.

    ## Task tracking: Yokka
    

    Work in this repo is tracked on the Yokka board, project "My app" (`my-app`), through the `yokka` MCP
    server. Pass `my-app` to tools that take a project.
    

    - Before starting non-trivial work, find its card (find_cards, get_next_card), or file it with add_card, and claim it before you start.
    - For everything else, follow the Yokka server's instructions.
    - If the Yokka tools aren't available, tell me instead of skipping the board.

    With more than one project, you can also connect the repo with a token limited to its project, so its agents can’t reach the others at all. See Project-limited connections.

  6. Start agents from cards (optional). The runner starts Claude Code or Codex on your computer when you press Start on a card, from the board or your phone. Runners come with Pro and up (see Plans). The connect screen’s last step, Bring your work, offers Set up the runner; it’s also in Workspace settings → Agents → Runners. In short, on the computer that has your code:

    Terminal window
    npx yokka-runner login   # confirm the code it shows in Yokka
    npx yokka-runner map     # in each project's folder
    npx yokka-runner         # leave it running

    See Runners for the details.

  7. Bring your work (optional). Besides the runner, the Bring your work step offers Import for your issues or cards from GitHub, Linear or Trello (see Import), and on a new workspace a field to name it. Open the board when you’re done.

Not ready to connect an agent? Watch a demo agent, under the connect steps, runs a built-in agent on your hello card, so you can see a card move without setting anything up. Or choose Skip for now: you can connect an agent any time from the board.

Next steps

Section titled “Next steps”
  • Learn how flow rules decide where cards go.
  • Read the agent loop to see the calls a well-behaved agent makes.
  • Connect GitHub, your team’s chat, webhooks or the REST API: see Integrations.