Workspaces & sessions

Workspaces

A workspace is the boundary an agent operates within.

• Physical workspace: a directory you choose on your machine. The agent works with its files directly.
• Virtual workspace: an isolated directory under ~/.prokopai/workspaces/<uuid>/. Use one for experiments that should not touch an existing project.

Add either from the workspace switcher. Permissions, memory, skills, learning, sessions, and MCP connections are scoped to the workspace. With several machines saved, the switcher lists the workspaces of every machine; see Client & mobile.

Worktrees

A Git workspace can have managed worktrees, each on its own branch. Bind a session to a worktree to keep its changes apart from the main checkout and from other sessions. Each worktree has its own color, shown as a chip next to its sessions, and the session list can group sessions by checkout.

Sessions in a worktree still use the workspace’s memory and skills, so knowledge saved there applies to the whole project.

A repository can describe how a new managed worktree gets ready in .prokop/worktree.json at its root:

{
  "copy": [".env"],
  "clone": ["node_modules"],
  "env": { "PORT": "{{port}}", "DATABASE_URL": "postgres://localhost/app_{{key}}" },
  "setup": ["bun install", "bun run db:create"],
  "teardown": ["bun run db:drop"]
}

• copy lists ignored files copied from the main checkout; clone lists directories cloned without taking extra disk space.
• env is written to .env.worktree (or envFile) and exported to the commands; files writes any other file from a template. {{port}}, {{port+1}} and so on come from a port block reserved for that worktree (ten by default, ports sets the size); {{key}} is a unique name for databases or topics; {{name}}, {{slug}}, {{path}} and {{rootPath}} are also available.
• Every target has to be ignored by Git, so the worktree stays clean and can be removed; a target that is not is refused with the path to add. A typo refuses creation with the line that is wrong.
• setup commands run in the background through your login shell after the worktree is created, and only after you approve them once per repository; a changed file asks again. The worktree is usable while they run. The Worktrees panel shows the running step, Run setup while the commands wait for approval, Retry and Log after a failure, and the reserved port once ready. teardown runs before the worktree is removed.
• A session in a worktree whose setup is still running, waiting, or failed gets one note at the start of its turn, on every runtime, so the agent waits instead of running its own install.

Instructions

Prokop includes two instruction files whenever it builds model context:

• ~/.prokopai/AGENTS.md applies to every workspace on the machine.
• <workspace>/AGENTS.md adds rules for one project.

# Project rules

- Use TypeScript strict mode
- Run the focused test before editing another package
- Never commit .env files

These are ordinary files. Keep project instructions in version control when the whole team should share them.

Memory, skills, and session search

Configure them per workspace in Workspace Settings → Memory & Learning. A new workspace starts with Memory and Skill management off.

Capability	What it adds	Default
Memory	Durable user preferences and project facts for this workspace	Off
Skill management	Lets agents create and update workspace skills	Off
Session search	Search and read earlier conversations	Always on

An enabled capability runs without asking per write. The files stay plain and inspectable.

Memory

Workspace memory is deliberately small:

• <workspace>/.prokopai/USER.md stores user preferences, up to 1,500 characters.
• <workspace>/.prokopai/MEMORY.md stores project facts, commands, and non-obvious fixes, up to 2,500 characters.

When Memory is on, both files are included in model context on each turn. You can read, edit, version, or delete them yourself.

Skills

Skills are conditional instruction sets stored at:

<workspace>/.agents/skills/<skill-name>/SKILL.md

Each skill has a name, a short trigger description, and a Markdown procedure. Unlike AGENTS.md, the procedure is not included automatically: the agent sees the skill descriptions and loads one with the skill tool when it matches the task.

---
name: release-check
description: Load before preparing a release
---

# Release check

1. Read the changelog.
2. Run the package-level checks.
3. Verify the built artifact.

With Skill management on, agents can also create, update, and patch workspace skills.

Session search

Agents can list, search, and read earlier conversations: in the current session, across the workspace, or across everything that agent has worked on in every workspace. It is always on and does not ask before reading.

Agents

An agent bundles a system prompt, tools, a default model, skill scope, and subagent rules. Every agent you chat with, such as the default agent, also has:

• Personal memory and skills that follow it into every workspace, kept in its home under ~/.prokopai/agents/<agent-id>/.
• A home workspace with its own sessions and files. You do not need to move a project into it to use the agent.
• Personal learning, described below.

Personal knowledge is separate from project knowledge. The agent uses its own agent_memory and agent_skill_manage tools for the first and the workspace tools for the second. Manage agents, their capabilities, learning, and their USER.md and MEMORY.md in Settings → Agents.

Agents can also write to each other. With message_agent, an agent sends another of your agents a request, a question, a status, a result, or an FYI; the recipient works on it as itself, in a conversation in its own home, with its own memory and skills, and keeps that conversation’s context across messages from the same sender. For a request or a question the answer comes back to the sender as a new message when the recipient’s turn ends. The Messaging section of agent settings sets whether other agents may write to this agent (off by default, since its memory is personal) and which agents it may write to. Conversations other agents started sit under From other agents in the home’s sidebar and count as the recipient’s own work for learning. Messages stop after six hops from your own turn.

Claude Code and Codex sessions run as an agent too: they receive its instructions and memory, plus Prokop’s memory, session search, and skill tools. See Configuration.

Learning

Learning reviews finished conversations and updates memory, and optionally skills. It edits knowledge files, not model weights, and uses your configured model, so reviews consume model usage separately from your conversations. It works for conversations on all three runtimes.

Learning	What it updates	What it reviews	Default
Agent learning	The agent’s personal memory, and its personal skills if Improve skills is on	Conversations the agent took part in, in its source workspaces	On
Workspace learning	Shared workspace memory, and workspace skills if Improve skills is on	Conversations in that workspace	Off

Turn agent learning off, or limit it to Selected workspaces, under Settings → Agents → Memory & Learning. Turn workspace learning on under Workspace Settings → Memory & Learning → Automatic learning; it can have several learners, each with its own agent, model, focus, and timing. Turning it on also turns on Memory for that workspace.

What counts

• Each workspace has a Use as personal learning source switch. Turning it off keeps that project’s conversations out of agent learning while its own workspace learning can stay on.
• A session’s menu offers Exclude from learning. Excluded conversations are never reviewed; exclusion does not erase knowledge already saved.
• Automated sessions, such as scheduled jobs, are skipped unless included, and learning never reviews its own runs.

Timing

Reviews do not run after every message. Each learner has three timing controls:

• Idle time: how long activity should be quiet before a review.
• Minimum interval: the cooldown between reviews.
• Maximum pending time: how long material can wait before a review runs even without a quiet period, still subject to the minimum interval.

Defaults: 30 minutes idle and a two-hour interval for workspace learning, 60 minutes idle and a 24-hour interval for agent learning, and a 24-hour maximum pending time for both.

History and undo

Each learning run is kept in a history with its source conversations. Runs on the Prokop runtime also record knowledge diffs and can be undone change by change without overwriting newer edits. Runs on Claude Code or Codex cannot be undone from history.

Sessions

A session is one conversation thread with its own history, runtime, model, agent, and run state. A workspace can hold any number of sessions. Open them as tabs, and split tabs right or down to see several at once.

Pick the runtime and model from the model picker. Model, effort, and agent stay changeable mid-session, and so does the runtime while the session is idle; see Runtimes.

Session controls

• Steer: send another message while the agent is working, and it goes into the running turn. Set Settings → Appearance → Messages sent while the agent works to Queue to send it after the turn instead.
• Stop: end the active generation and its running subagents.
• Edit and Undo: change an earlier prompt, or go back to it and discard what came after.
• Fork: branch at a message and continue in a separate session.
• Compact: summarize older context when a conversation approaches the model limit.

Delegation

An agent can be allowed to hand work to other agents, with the same tools on Prokop, Claude Code, and Codex; see Prokop Delegation.

• Subagents. A delegation names a role you defined, which runs on its own runtime and model, or on the parent’s when it sets none. A role pinned to Claude Code or Codex runs there even from a Prokop session. Each subagent has its own message history, works in the same workspace, shows up live, and can be opened later. Delegation is limited to two levels of depth and eight running subagents under one session.
• Sessions in their own worktrees. From one conversation an agent can start top-level sessions, each on a new branch in a new managed worktree with the repository’s setup applied. These are ordinary sessions: open one, continue there, review the diff, and merge. The agent hears when each finishes and when one needs an answer. Three can run from one conversation at a time.
• What needs your yes. Each agent’s Delegation targets setting says whether it may pick any enabled runtime, ask each time, run roles only as configured, or use specific runtimes without asking; a new agent asks. New sessions does the same for worktree sessions. The question shows on the session you are looking at, with Allow once, Allow for this agent, or Deny. A child never gets a wider permission mode than its parent.

Groups

A group is one shared thread between you and 2 to 10 of your agents in a workspace. Groups sit in the sidebar under the sessions and open as a tab in the center.

• Members and routing. Type @ in the message box to pick a member or everyone; a message that mentions nobody goes to the group’s default member. Type / to send one of your prompts, as in a session.
• Each member answers from its own session, on its own runtime and model, so Prokop, Claude Code, and Codex agents sit in the same group. A woken member receives everything said since it last spoke, labeled by author, and its finished reply is posted to the group as that member, with each tool call as one summary line. Long gaps are capped at the newest 50 messages, and group_history reads the rest. Member sessions stay out of every session list; open one from the member’s menu.
• Handoffs. A member can pass a distinct next stage to another member; the handoff shows as one line naming both. Handoffs and agent messages share a limit of six hops from your own turn.
• One permission mode. The shield in the group’s message box is the setting for every member, applied at once and to members added later. Members’ approvals and questions are answered under the thread.
• Stop. While members work, the send button is Stop and interrupts every working member; a single member stops from its chip’s menu. Deleting a group stops and deletes its member sessions.

Goal mode

Goal mode turns one request into a bounded multi-turn loop.

1. Choose Goal instead of Chat.
2. Define a completion condition and the maximum number of turns.
3. The agent works, then a separate evaluator checks the available evidence.
4. If the condition is not met, the agent gets another turn.

The evaluator checks the recent conversation and tool output rather than trusting a claim that the task is done. A goal ends as met, failed, or cancelled, and you can stop it at any time. Claude Code and Codex sessions use their CLI’s native goals.

MCP connections

Each workspace can connect to local stdio or remote Streamable HTTP/SSE MCP servers, with OAuth handled by the server. Configuration lives in <workspace>/.prokopai/mcp.json. Connected MCP tools appear alongside Prokop’s built-in tools. See Configuration for the file format.

Terminals

The client includes persistent terminals with multiple tabs. They belong to the workspace, keep running while the panel is hidden, and survive switching between your recent projects. Drag tabs to reorder them; the order is kept per workspace on each device.

Data locations

Data	Location
Sessions, messages, permissions	~/.prokopai/data/agent.db
Global instructions	~/.prokopai/AGENTS.md
Workspace instructions	<workspace>/AGENTS.md
Workspace memory	<workspace>/.prokopai/USER.md and MEMORY.md
Workspace skills	<workspace>/.agents/skills/
Agent home workspace	~/.prokopai/agents/<agent-id>/home/
Agent memory	~/.prokopai/agents/<agent-id>/USER.md and MEMORY.md
Agent skills	~/.prokopai/agents/<agent-id>/skills/
MCP configuration	<workspace>/.prokopai/mcp.json

Next: review the tool catalog, configure runtimes and providers, or work with pull requests.