Personas

Introduction

Out of the box, your Laraclaw agent is a generic helpful assistant — perfectly fine, but a bit... beige. What if you want it to sound like an ops engineer who keeps replies short? Or a friendly support rep who always signs off the same way? Or a project manager who answers in bullet points?

That's what personas are for.

A persona is a Markdown file that gets appended to the agent's base system prompt. Personas change how the agent talks — its tone, focus, and conventions — without touching any code. Drop a file on disk, point a thread at it, done.

Let's see how they work.

Where Personas Live

Personas live under LARACLAW_PERSONAS_PATH, which defaults to laraclaw/personas/ at the root of your project.

Each persona is a single .md file. No frontmatter, no directory structure — just the prompt content:

laraclaw/
  personas/
    default.md
    ops.md
    pm.md

The filename (without .md) is the persona's name, so ops.md is the ops persona. Pretty simple, right?

One name is special: default.md is picked up automatically. Drop it in and it applies to every thread, with nothing to configure. vendor:publish --tag=laraclaw writes a starter copy, so you may already have one.

!TIP After adding or editing a persona, restart the queue worker so it picks up the change. Long-lived processes cache the resolved persona path at boot. The terminal connector boots fresh every time, so it sees edits immediately.

Setting a Default Persona

Want every new thread to start with a specific persona? Set it in your .env:

LARACLAW_PERSONAS_DEFAULT=ops

The value is the filename without the .md extension, and it wins over default.md.

So the resolution order for a thread with no persona of its own is:

1. LARACLAW_PERSONAS_DEFAULT, if set and the file exists
2. default.md, if it exists
3. no persona at all, just the base prompt

!NOTE An empty LARACLAW_PERSONAS_DEFAULT= counts as unset, so it falls through to default.md rather than disabling personas. To run with no persona, delete default.md instead.

Switching Personas at Runtime

Each Thread has its own persona, stored in the persona column of laraclaw_threads. The active persona is whatever the thread says it is — independent per Telegram chat, per Slack channel, per email thread.

The agent switches personas by calling the built-in Persona tool. So a user can just ask in chat:

"Switch to the ops persona."

The agent calls the Persona tool's switch operation, the thread is updated, and the new persona takes effect on the next message. No restart, no config edit.

The same tool supports two more operations:

• list — see what personas are available. Great for "remind me what personas I have."
• clear — drop the override and revert to LARACLAW_PERSONAS_DEFAULT (or no persona, if there's no default).

Writing a Persona

A persona file is just instructions. Keep them tight — the agent already has a base prompt, so you only need to override the parts that matter.

Here's an example for a Laravel-flavored coding assistant:

You are a senior Laravel developer who answers questions with code first and
explanation second. When you write code, you follow these conventions:

- Use single quotes for strings unless interpolation is required.
- Prefer collection methods over array_* functions.
- Use match instead of switch.
- Write methods with explicit return types, including : void.

When asked a conceptual question with no code in the answer, keep your reply
to three sentences or fewer.

The persona content is appended to the base system prompt, so anything in the base prompt still applies — you're shaping the agent, not replacing it.

Addressing People by Name

The agent is told who sent the message, so a persona can use the sender's name directly:

Address the user by their first name once per reply, no more.

The name is read off the inbound message rather than off the thread's owner, which matters in a group chat: a Telegram group resolves to your configured owner user, but each message still carries the name of whoever actually typed it. In a group the agent is also told that other people may be present, so it does not assume every message comes from the same person.

!WARNING That name comes from a profile the sender controls, so treat it as a label rather than proof of identity. Laraclaw flattens it to a single short line before it reaches the prompt, and it grants no permissions on its own. Do not write a persona that hands out anything sensitive based on a name alone.

A few tips for writing good personas:

• Be specific about format. "Reply in bullet points" gets more reliable behavior than "be concise."
• Lean on examples. "Sign off with 'Cheers, your assistant.'" beats "be friendly at the end."
• Don't redefine tools. The base prompt already explains what the agent can do — don't duplicate that. Personas shape how, not what.
• Keep it short. A persona that's a wall of text becomes a wall of context every turn. 10–30 lines is a healthy zone.

Clearing a Persona

To revert a thread to the default, ask the agent to clear the persona, or call the Persona tool's clear operation directly. The persona column is set back to null and the next message uses whatever LARACLAW_PERSONAS_DEFAULT resolves to.

What's Next

• Want the agent to follow procedures rather than just shift tone? You're looking for Skills.
• Want to change the base prompt that personas overlay? Edit laraclaw/instructions.md (published by vendor:publish --tag=laraclaw).

Until next time!