Persona Configuration

After creating a persona, the detail page provides seven tabs for configuring every aspect of the agent’s behavior: Configuration, Instructions, Context, Skills, Activity, Analytics, and Related. This guide covers each tab in depth, with best practices and recommendations for every setting.

Configuration Tab

The Configuration tab controls the core runtime behavior of the persona: which tool it uses, which model it runs, and how deeply it reasons about problems.

CLI Tool Selection

The CLI tool determines which AI coding agent runs inside the sandbox. CodeCourier supports multiple tools, each with its own strengths:

• Claude Code (claude) - Anthropic’s coding agent. Best for complex code generation, multi-file changes, and deep reasoning tasks. Supports thinking effort up to “max”.
• OpenCode (opencode) - Open-source alternative with support for multiple model providers. Good for teams that need flexibility in model choice.
• Codex (codex) - OpenAI’s coding agent. Best for tasks that benefit from GPT models.

When you change the CLI tool, the model dropdown automatically updates to show only the models available for that tool. If the currently selected model is not available on the new tool, it resets to the tool’s default model.

Model Selection

The model determines the specific LLM that powers the agent. Available models depend on the selected CLI tool. For Claude Code, typical options include:

• claude-opus-4-6 - Highest capability, best for complex tasks. Higher cost and latency.
• claude-sonnet-4-6 - Good balance of quality and speed. Recommended for checker and prompter roles.

Choose the model based on the persona’s role. Designers, deep-dive agents, and optimizers typically benefit from the most capable model (Opus), while checkers, reviewers, and prompters work well with faster models (Sonnet) since their tasks are more constrained.

Thinking Effort

Thinking effort controls how much reasoning the model applies before producing output. Higher effort leads to better results on complex problems but increases latency and cost.

Learning Injection

When enabled, the persona’s sessions automatically receive the active compiled learnings for its role type. Learnings are knowledge captured from past runs - patterns, gotchas, preferences, and best practices that improve agent behavior over time.

Each learning version is compiled per role type (designer, checker, etc.), so a designer persona receives designer-specific learnings while a checker persona receives checker-specific learnings. This toggle lets you disable injection for personas that should start fresh without historical context.

Enable/Disable Toggle

The isEnabled toggle controls whether the persona is active and selectable in workflow pipeline configurations. Disabling a persona hides it from the persona picker in workflow editors without deleting it. This is useful when a persona is under revision and should not be used in production workflows until it is ready.

Instructions Tab

The Instructions tab provides a free-form text area for defining the persona’s system-level behavior. These instructions are injected into the agent’s context at the start of every session and shape how it approaches tasks.

Writing Effective Instructions

Good persona instructions are specific, actionable, and structured. Here are patterns that work well:

## Role
You are a senior frontend engineer specializing in React 19
and Tailwind CSS v4.

## Standards
- Use functional components exclusively
- Extract reusable logic into custom hooks
- All components must have TypeScript interfaces for props
- Prefer server components where possible
- Use the project's existing design tokens from globals.css

## File Organization
- Components go in components/{feature}/
- Hooks go in hooks/
- Never create barrel (index.ts) files

## Testing
- Write unit tests for all utility functions
- Include at minimum one integration test per component
- Use Vitest and React Testing Library

Instruction Best Practices

• Be explicit about what NOT to do - Constraints are as important as instructions. Tell the agent what to avoid.
• Use structured sections - Headers and numbered lists make instructions easier for the model to follow.
• Reference project conventions - Mention specific file paths, naming patterns, and tools used in your codebase.
• Keep it focused - A persona for checking should not include implementation instructions. Each persona has one job.
• Test and iterate - Run the persona in a few workflows, review the output, and refine the instructions based on what goes wrong.
• Complement, don’t duplicate context - If you have a bound Context document covering architecture, don’t repeat that same information in the Instructions field. Let each serve its purpose.

Context Tab

The Context tab allows you to bind a Context document to this persona. Context documents are project-level markdown resources - architectural summaries, coding standards, API reference guides, onboarding notes, or any reference material that an AI agent should have access to during its session.

How Context Binding Works

When a context document is bound to a persona, the context’s active version markdown is automatically prepended to the sandbox configuration at the start of every session that uses this persona. The agent receives the context content before it receives the persona’s own instructions, so the context acts as foundational background knowledge.

To bind a context:

1. Navigate to the Context tab on the persona detail page.
2. Click Select Context to open the context picker.
3. Choose from the list of available project contexts. Only contexts with an active version appear in the list.
4. Save. The binding is stored as contextId on the persona record.

When to Use Context Binding vs. Instructions

Skills Tab

The Skills tab gives this persona access to packaged domain knowledge, shell commands, and executable scripts. It is organized into three sub-sections: Skills, Commands, and Scripts.

Skills

Skills are curated sets of reference files, best practices, and API documentation for specific technologies. The Skills section shows all enabled skills in the project as a checkbox grid. Each skill card displays the skill name, description, and file count. Select the skills that are relevant to the persona’s role:

• A frontend designer might need: frontend-design, vitest-testing
• A backend designer might need: convex-implementation, zod-validation
• A checker might need: app-security, superpower-codereview
• A reviewer might need: app-security, performance-optimization-addyosmani
• A planner might need: superpower-debugging, convex-implementation

Commands

Commands are shell commands or aliases that are injected into the sandbox environment at session start. They give the agent access to project-specific CLI operations, custom build scripts, or utility commands without requiring the agent to know their full implementation.

The Commands section shows all commands defined in the project as a checkbox list. Each command entry displays its name, alias, and a brief description of what it does. Select the commands that the persona needs access to during its sessions. Selected command IDs are stored in selectedCommands on the persona record.

Example use cases for command injection:

• A designer persona that needs npm run typecheck and npm run lint
• A checker persona that needs a custom validate-schema command

Scripts

Scripts are executable script files that are injected into the sandbox filesystem at session start. Unlike commands (which are typically aliases or one-liners), scripts are multi-step programs that the agent can invoke by name.

The Scripts section shows all scripts defined in the project. Each entry displays its name, language (bash, python, node), and a description. Selected script IDs are stored in selectedScripts on the persona record.

Activity Tab

The Activity tab shows a paginated table of all run steps executed by this persona. Each row includes the linked run, step status (completed/failed/running), iteration number, and timestamps. This gives you a history of how the persona has performed across workflow runs.

Use the activity feed to identify patterns: if a persona consistently fails on a particular type of task, review the failure messages to refine its instructions. If a persona regularly requires many iterations before passing a checker, consider increasing its thinking effort or enriching its skills.

Analytics Tab

The Analyticstab provides time-series visualizations of the persona’s performance. You can filter by time period (7 days, 30 days, 90 days) and granularity (daily, weekly, monthly). The following metrics are tracked:

The quality score is particularly valuable for tracking whether instruction changes are having a positive effect. After refining a persona’s instructions, check the quality score trend over the following week to confirm the improvement.

Cost data is broken down by service category using the project’s usage records, giving you visibility into which component of each run (model inference, sandbox execution, etc.) is the primary cost driver.

Related Entities Tab

The Related tab shows entities connected to this persona: workflows that have used it, issues linked to its runs, and learning versions compiled for its role type. This provides a quick way to navigate from a persona to all the work it has been involved in across the project.

Persona Versioning

Every time you save changes to a persona’s instructions or configuration, CodeCourier creates a new version record rather than overwriting the existing one. The version history is accessible from a Version History panel on the persona detail page.

Key versioning behaviors:

• The version field increments with each save (1, 2, 3, …).
• The newest version automatically becomes isLatest: true.
• All new workflow runs use the latest version.
• The parentPersonaId field links each version to its predecessor, forming a chain.
• You can promote any previous version back to latest from the version history panel, creating a new version record that mirrors the promoted content.

Next Steps