Docs

Getting started

Install Pekan, create your first project, and get work onto the board by hand or by asking an agent.

Pekan is a desktop application. You download it, open it, and it runs entirely on your own machine: your projects live in a local SQLite database, attachments live on your local filesystem, and there is no account to create and nothing to sign in to.

Install

Pekan is in a public alpha. Download the latest build from the releases page. Windows x64 is available as an installer or portable ZIP, and Linux x64 is available as an AppImage or tar archive. Every release lists SHA-256 checksums you can verify before running it.

The alpha builds are not code signed, so Windows SmartScreen will warn you the first time you run one. Choose More info, then Run anyway. Updates are manual during the alpha: download the newer build and install it over the old one.

macOS and Linux builds are not published yet.

When Pekan starts it also starts two local services in the background:

Both bind to the loopback address, so nothing is exposed to your network. If either port is already taken, Pekan picks the next free one, which is why you should always read the live MCP URL out of the project's config file rather than hard-coding 3848 anywhere.

Create your first project

Click New project in the sidebar. Four fields matter:

• Name is the display name, for example Apollo.
• Prefix is a short uppercase code used in task ids, for example APL, which gives you task ids like APL-128. Pekan suggests one from the name. Pick something short and stable, because it shows up in every task reference from then on.
• Directory links the project to a folder on disk, normally the repository you are working in. This is what makes agent setup, the file tree, the terminal, and the Git view possible, so set it if you have one.
• Workflow decides the starting columns. Default gives you Backlog, Todo, In Progress, Review, and Done. Simple gives you Todo, In Progress, and Done. You can change columns afterwards, and you can build your own workflow later.

The board

A project opens on its Tasks tab: columns left to right, cards inside them. Drag a card to move it between columns, or open it and change its column from the task detail.

Two columns can carry a role, which is what lets automation and agents talk about them without knowing your column names. A column with the review role is where move_to_review sends work, and a column with the done role is where complete_task sends it. In the Default workflow, Review and Done carry those roles. If your project has no review column, move_to_review has nowhere to go, which is deliberate: Pekan supplies board mechanics, not a definition of done.

Create your first task

A new project opens with empty columns, so the next thing is work on them. You can put it there by hand, and for the first card or two you probably should, because it takes seconds and shows you the shape of the record.

• Add task at the foot of any column takes a title and nothing else. Type it, press Enter, and the card lands at the bottom of that column. This is the one to use when you are capturing a thought before it evaporates.
• Right-click the board background and choose New task to create a card in the first column and open it immediately. Replace the placeholder title, write the description, and set the rest while you are already in the record.

Opening a card gives you the whole record, which What a task holds below walks through. Fill in as much as the work needs and no more. A one-line card sitting in Backlog is a perfectly legitimate task. It is just not one an agent can act on yet.

Let an agent write them instead

Typing cards by hand stops paying off quickly, and a task written in ten words rarely carries enough for anyone, human or agent, to pick it up cold. The better habit is to describe the outcome you want in a sentence or a paragraph and have a coding agent turn that into tasks. It can read the repository first, split the work along boundaries that actually exist in the code, and write each card with the acceptance criteria the next agent will need.

Agent-written tasks are ordinary tasks. They arrive through the create_task tool on the same MCP server the app itself uses, they land in the column the agent was told to use, and the activity log attributes each one to the named agent that created it.

All of this needs the one-time Agent setup on the next page, which is what gives an agent the board tools. Once that is done, there are three surfaces to choose from, and they all write to the same board:

• The Agent Panel, inside Pekan. Open the project's Workspace, start a session with Codex or Claude, and ask for the tasks in plain language. Nothing leaves the app, you can correct it mid-conversation, and the cards appear on the board as it creates them. Start here. See Agent Panel.
• A terminal, either the one in the Workspace or your own. Run Claude Code, Codex, or another CLI in the project directory and ask for the same thing. After setup the board tools are already registered for that directory, so there is nothing further to wire up.
• A third-party MCP client, such as Claude Desktop or any other MCP-aware app. Setup does not configure these, so you add the board yourself as a local stdio server that runs node .mcpekan/mcp-proxy.cjs from the project directory. Connect your agent covers which clients setup writes config for, and what to paste in for the rest.

Whichever surface you use, a prompt that names the column, the scope, and the size of task you want back produces better cards than "add some tasks":

Read the repository, then create tasks in Backlog for replacing the session
cookie with a signed JWT. One task per shippable step, each with acceptance
criteria in its description. Do not start any of the work yet.

That last sentence earns its place. An agent with write access to both the board and the repository will often carry straight on into implementing what it just planned unless you tell it where to stop.

For a card that turns out to be too big once it exists, the Break down agent action does the same job for one task: it creates sibling tasks that together complete it. See Agent actions.

What a task holds

Open a card to see the whole record. A task carries a title and a Markdown description, an assignee that can be a person or an agent, a priority, tags, start and due dates, dependencies on other tasks, attachments, comments, and a full activity history.

That history is the part worth understanding early. Every status change, assignment, comment, and move is attributed to whoever made it, human or agent. When an agent moves a task and leaves a comment, you get a record of what happened and when, not a notification you have to catch in the moment.

Finding things

Press Ctrl K, or ⌘ K on macOS, to open search from anywhere. It searches across projects and tasks, matching titles, descriptions, and task ids. Arrow keys move between results, Enter opens one, and Esc closes it.

The in-app Help page carries the full keyboard reference, including the workspace and terminal shortcuts, and adapts the modifier key to your platform.

Next

Pekan on its own is a kanban board. The reason it exists is the next page: connecting a coding agent so it reads and writes the same board you do.