Docs

Agent Panel

Start and steer a project-scoped conversation with Codex or Claude, review access requests, attach task context, and return to earlier sessions.

The Agent Panel is a conversation with a coding agent inside a project's Workspace. It streams the agent's response, plans, tool calls, access requests, and file changes beside the Files and Diff panel, so you can steer work and inspect the checkout without leaving Pekan.

It is one of three ways to run an agent. Pick the surface that matches the job:

Install a conversational provider

Pekan currently supports two Agent Client Protocol (ACP) adapters:

The adapter is separate from Pekan and is not downloaded automatically. Install it yourself, then complete any sign-in or provider configuration its own tooling requires. Pekan detects commands available on your PATH; a missing adapter stays visible with its copyable install command.

This setup is separate from connecting an external MCP client. Run the project's Agent setup too if you want the conversation to receive Pekan's board tools. Without .mcpekan/mcp-proxy.cjs, the session can still work with project files, but its header says that board tools are unavailable.

Start a session

1. Link a local directory to the project. The Agent Panel is unavailable for a project without one.
2. Open the project's Workspace, then expand the Agent Panel on the right. Use Ctrl Shift A, or ⌘ Shift A on macOS, to show or hide it.
3. Choose Codex or Claude.
4. Leave Model on Use provider default, or choose one of the available models.
5. Choose Read only or Write access.
6. Choose Ask each time or Auto approve.
7. Select Start session, write a message, and send it.

Pekan loads available models when you choose a provider. No message is sent during setup. Your model choice applies only to this conversation and does not change your provider settings. Changing provider or access restarts setup and resets the model choice.

If your adapter does not offer model choices, you can still start with its default. If loading fails, choose Reload models or start with the provider default. You can cancel loading or close the panel. If a selected model is rejected, Pekan shows an error before you send a message; reload and choose again.

The session header shows the model reported by the provider, or Model not reported when it is unavailable. Resuming a conversation reads its current model from the provider. Model switching during a conversation is not available here.

You can also open a task and choose its Agent workspace affordance. That opens the Workspace with the task ready as the session's primary context.

The current defaults are Write access and Auto approve. Review both choices before starting if you only need an explanation or want to approve every request yourself.

Choose access and approvals

The access choice fixes the broadest scope Pekan will grant for that session. Changing approval mode later never widens it.

• Read only offers project file reads, but Pekan does not offer its file-write capability or command capability. If the agent asks for a mutating permission anyway, allow options are disabled and the transcript records that the session scope refused them.
• Write access lets Pekan mediate file writes inside the linked project directory. Paths on another drive, .. traversal, and symlink or junction escapes are refused by Pekan's filesystem bridge.

Approval mode decides how Pekan answers requests that remain inside that scope:

• Ask each time leaves each permission and MCP tool request on screen for you. You can allow or deny once, or for the rest of the session, when the provider offers those choices.
• Auto approve selects an allowed option for agent permission requests and recognizes the provider's specific MCP tool approval prompt. It prefers one-time permission when the provider offers it. Generic questions and forms are never filled automatically.

You can switch Ask each time and Auto approve in the session header. The change applies only to future requests. It does not answer a request already waiting, revoke a decision already sent, restart the adapter, or change read-only versus write access.

Send task context and files

A session opened from a task sends that task's context with the first message. In any composer, type @ followed by a task id or title to attach another task to that turn.

Task context includes the task identity, project and column, priority and blocked state, descriptions, extracted acceptance criteria, the latest handoff, and a bounded set of recent comments. Pekan reports any trimming before send. It does not include task attachments, the full activity log, or the assignee.

Attaching context does not assign or claim the task. While a turn is active against its primary task, the card shows the same transient working indicator used by other agent surfaces. Read-only sessions can show that they are viewing a task without changing its ownership.

Use the attachment control for supported text files and images. The connected provider decides which prompt content types it accepts, so an unsupported image control is hidden or refused. If voice dictation is enabled, recorded speech is transcribed into editable composer text and is not sent until you send the message yourself.

Steer a turn

The transcript distinguishes the agent's answer, collapsed reasoning or progress, structured plans, tool calls, terminal output reported by the provider, diffs, access decisions, and questions that need your input. Successful tool calls fold down after completion; running calls and failures stay open. Select an in-project file location or diff to open it in the Files panel.

The header reports the session state: connecting, sign in, ready, working, closed, or failed. It also shows elapsed time, the fixed access scope, approval mode, board-tool availability, and provider-reported context usage or cost when available. Type / at the start of a message to choose from commands the connected provider actually advertises. Compact context appears only when the provider advertises a command named compact, and it is available only while the session is idle.

When the agent asks for structured input, answer the displayed fields or decline. Auto approve does not answer these general elicitation forms. Select Stop to cancel the active turn. Stopping also settles any unanswered request as not approved.

Queue follow-up messages

Sending while a turn is working adds the message to that session's first-in, first-out queue. The queue keeps its text, task mentions, and attachments. You can edit or remove a waiting item until dispatch starts.

The next message is sent only after the current turn ends successfully. A stopped, failed, or refused turn leaves later messages waiting instead of starting unexpected work. A failed queue item blocks the items behind it until you retry or remove it. Queues persist across navigation and app restarts.

Close, resume, and revisit sessions

The session sidebar lists conversations for the current project, newest activity first. The plus button always starts a new session; choose an existing row to switch conversations. Collapsing the Agent Panel does not stop its current turn.

Close ends a live provider session when that provider advertises close support. Resume starts a fresh adapter process and asks the provider to load its saved session when load support is available. A session that never connected cannot be resumed. Controls that the provider does not support are omitted rather than shown as inactive promises.

Remove deletes Pekan's conversation record after the session has stopped. It does not undo file changes, delete Git branches or worktrees, unassign tasks, or reverse anything the agent already did.

Review file and Git changes

Write-access sessions edit the linked checkout directly. They do not create a branch, commit, push, or isolated worktree merely because they run in the Agent Panel. Whether the provider proposes or performs a Git operation depends on the provider, its tools, your prompt, and the approvals involved.

Keep Files or Diff open beside the conversation to review changed files. The Git view shows the repository's current changed files and unified diffs. Removing or closing the conversation never discards those changes, so use Git itself to keep, commit, revert, or separate the work.

Privacy and data flow

Pekan launches the selected ACP adapter as a local child process and sends it your prompts plus the context and attachments you choose. The adapter and its underlying provider may then process that material according to the provider account, configuration, and privacy terms you use.

The adapter may receive project content it reads through its own tools or through Pekan's bounded project-file bridge. When Agent setup is present, Pekan also offers the project-scoped board MCP proxy, which can expose task and project records under that connection's permissions. Do not attach secrets or task context you would not send to the selected provider.

Pekan stores its session record, transcript events, queue, and provider-reported usage locally with the desktop app. Voice dictation is a separate path: when enabled, it uses the transcription API configured in Settings, inserts only the returned text into the draft, and does not send that draft to the agent automatically.

Troubleshoot a session

No provider is available. Install one of the adapter packages shown above, confirm its command is on PATH, then restart Pekan so the desktop process sees the updated environment. Use the adapter's setup link for provider-specific help.

The session fails while starting. Check the visible failure state for a missing adapter, spawn failure, protocol mismatch, sign-in requirement, malformed message, adapter crash, or exit. Confirm the provider's own CLI or adapter can start with your current account configuration.

The project has no Agent Panel. Link a local directory in project settings. A non-Git directory is valid for conversation and file work, but Git and Diff features require a Git repository.

Board commands are unavailable. Open Workspace > Agent setup and run setup or repair. The session header confirms whether Pekan forwarded the board proxy. A conversation can still use files when board forwarding is unavailable.

A file or action is refused. Check the session's fixed access scope first. Project file access cannot cross the linked directory through Pekan's bridge. An approval mode change cannot turn a read-only session into a write session; start a new session with the scope you intend.

The session is disconnected or closed. Use Resume only when it appears. Resume requires a provider session id and provider load support. If it is absent or resume fails, start a new session and restate the needed context.

A command or Compact context is missing. Pekan shows only commands advertised by that specific connected session. Availability can differ by provider, adapter version, authentication state, or session.