Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.clideck.dev/llms.txt

Use this file to discover all available pages before exploring further.

Roles let you define what an agent should do — and what it shouldn’t. When you assign a role to a session, CliDeck injects the role’s instructions into the agent at startup and tags the session with the role name. The agent adopts that identity for the entire session. This is useful when you run multiple agents on the same project. Instead of typing the same system prompt every time, define roles like Programmer, Reviewer, and Product Manager once, then pick them from a dropdown when you create a session.

​
Roles vs Prompts

Both roles and prompts send text to an agent. The difference is that roles are part of the session’s identity. When you assign a role, CliDeck tags the session with the role name and instructions. This metadata is visible to plugins and internal subsystems — they can read which role an agent has and act on it. Autopilot uses this to understand each agent’s responsibilities and route work between them. A prompt is a one-shot paste. It goes to the terminal and that’s it — CliDeck doesn’t track it or expose it to anything else.

​
Creating a Role

Open the Roles panel from the sidebar rail. Click the + button at the top. Each role has two fields:
  • Name — A short label (up to 40 characters). This is what you’ll see in the session launcher and in Autopilot logs.
  • Instructions — The full system prompt injected into the agent. This is where you define responsibilities, restrictions, and behavior.
Click Save to create the role. Press Escape to cancel.

​
Writing Good Instructions

Role instructions are sent directly to the agent as a prompt. Write them the way you’d write a system prompt — clear, direct, specific. A good role includes:
  • What the agent is responsible for — “You are the code reviewer. Check for critical issues, logic flaws, and ugly workarounds.”
  • What it should not do — “You never write code.” or “Do not use plan mode.”
  • How it should report — “List your findings concisely.” or “When done, summarize what you changed.”
Keep instructions focused. A role that tries to do everything is no different from no role at all.

​
Assigning a Role to a Session

When you open the session launcher (click +), a Role dropdown appears if you have at least one role defined. Select a role before clicking an agent button. When you select a role:
  • The session name auto-fills with the role name (you can override this)
  • The role’s instructions are queued for injection
After the agent starts and produces its first output, CliDeck waits 3 seconds, then types the role instructions into the terminal and presses Enter. The agent receives them as its first prompt.
Role injection happens once, at session start. It’s the same as if you typed the instructions yourself — the agent sees a normal user message.

​
Editing and Deleting

Hover over any role in the list to reveal the edit and delete buttons.
  • Edit — Opens the editor with the existing name and instructions pre-filled.
  • Delete — Removes the role immediately. Existing sessions that were created with this role are not affected.

​
Starter Roles

New CliDeck installations include three demo roles to get you started:
RolePurpose
ProgrammerMain coder — builds immediately, prefers pure solutions over workarounds
ReviewerCode reviewer — finds critical issues and logic flaws, never writes code
Product ManagerFocuses on UI/UX and user impact, never writes code
These are fully editable. Modify them, delete them, or add your own.
Starter roles are only seeded on first run when no config exists. Existing users keep their current configuration untouched.

​
Storage

Roles are stored in ~/.clideck/config.json under the roles array. They sync across all connected browser tabs automatically.