Claude Code can work with Action Llama in two ways: editing your project files using the CLAUDE.md context file, and interacting with the running scheduler through the MCP server. Both are set up automatically when you create a new project with al new.
CLAUDE.md — project context for Claude Code
Every al new project includes a CLAUDE.md at the project root. This is a symlink to a reference document shipped with the @action-llama/action-llama package that contains everything Claude Code needs to work on an Action Llama project:
- How agent configuration works (SKILL.md for portable metadata + instructions, config.toml for runtime config)
- How agent prompts are assembled at runtime (system prompt, user prompt blocks, trigger context)
- Available agent commands (signals, subagent calls, resource locks)
- Credential context and environment variables
- Filesystem constraints inside the Docker container
When you open your project in Claude Code, it reads CLAUDE.md automatically. This means you can ask Claude to create new agents, edit SKILL.md instructions, configure webhooks, and adjust agent params — and it understands the full context of how Action Llama works.
What you can do
- “Create a new agent that monitors Sentry for new errors and opens GitHub issues” — Claude writes a
SKILL.md with instructions and a config.toml with the right runtime config (credentials, schedule, webhooks).
- “Add webhook support to the dev agent for issue comments” — Claude edits the
config.toml to add a webhook trigger and updates the SKILL.md instructions to handle both scheduled and webhook triggers.
- “Change the reviewer agent to use GPT-4o” — Claude updates the
models field in the agent’s config.toml.
- “The dev agent keeps force-pushing, fix the instructions” — Claude reads the SKILL.md body and adds explicit rules.
Claude Code reads CLAUDE.md from the project root automatically. You don’t need to paste documentation or explain how Action Llama works — it already knows.
Slash commands — development workflows
Action Llama projects include five Claude Code slash commands in .claude/commands/. These are markdown prompt templates that you invoke with /<name> in Claude Code to perform common development workflows.
New projects created with al new include these automatically. For existing projects, run:
Available commands
| Command | Description |
|---|
/new-agent <name> | Create a new agent interactively — asks for trigger type, schedule, credentials, then writes the SKILL.md |
/run [agent] | Start the scheduler if needed, trigger an agent run, and summarize the results |
/debug [agent] | Pull recent warnings/errors, read the agent’s SKILL.md, and diagnose the root cause with a concrete fix |
/iterate [agent] | Run → analyze → edit instructions → repeat (up to 3 cycles) until the agent runs cleanly |
/status | Rich overview combining scheduler state and agent details into a formatted table with actionable suggestions |
Usage
Commands that accept an agent name use Claude Code’s $ARGUMENTS mechanism — type the command followed by the agent name:
/run dev
/debug reviewer
/new-agent my-new-agent
al new and al mcp init.
Slash commands live in .claude/commands/ as plain markdown files. You can customize them or add your own — Claude Code discovers them automatically.
MCP server — live gateway interaction
The MCP server lets Claude Code interact with a running Action Llama scheduler over stdio. Instead of switching to a terminal to check status, trigger runs, or read logs, you can ask Claude directly.
Setup
New projects created with al new include a .mcp.json file that Claude Code discovers automatically:
{
"mcpServers": {
"action-llama": {
"command": "al",
"args": ["mcp", "serve"]
}
}
}
.mcp.json in the project root. Claude Code picks it up on next launch.
How it works
When Claude Code starts, it spawns al mcp serve as a subprocess. The MCP server communicates over stdin/stdout using JSON-RPC. Under the hood, it calls the same gateway HTTP API that the CLI uses — so anything you can do with al commands, Claude can do through the MCP server.
Claude Code <--stdin/stdout--> al mcp serve <--HTTP--> al start (gateway)
|
filesystem (agents/, .al/logs/)
al_:
| Tool | Description |
|---|
al_start | Start the scheduler. Spawns al start --headless in the background and waits for the gateway to become ready. |
al_stop | Gracefully stop the scheduler. |
al_status | Show scheduler state, agent states, running instances, and queue sizes. |
al_agents | List agents with config, schedule, and webhooks. Pass a name for details including SKILL.md body. Works offline. |
al_run | Trigger a single agent run. |
al_logs | View agent or scheduler logs with time, instance, and level filtering. |
al_pause | Pause the scheduler or a single agent by name. |
al_resume | Resume the scheduler or a single agent by name. |
al_kill | Kill an agent (all instances) or a single instance by ID. |
Example conversations
Check what’s running:
“What’s the status of my agents?”
Claude calls al_status and shows scheduler state, which agents are idle/running/paused, and queue depths.
Trigger a run and watch the result:
“Run the dev agent and show me what it did”
Claude calls al_run with name dev, waits a moment, then calls al_logs to show the agent’s actions in conversation format.
Debug a failing agent:
“The reviewer agent keeps erroring out. Show me the last few runs.”
Claude calls al_logs with name reviewer, level error, and reviews the output. It can then read the SKILL.md via al_agents and suggest fixes.
Start everything from scratch:
“Start the scheduler and pause the devops agent — I only want dev running right now”
Claude calls al_start, waits for it to come up, then calls al_pause with name devops.
Log viewing
The al_logs tool supports the same filtering as the CLI:
| Parameter | Description |
|---|
name | Agent name, or "scheduler" for scheduler logs |
lines | Number of entries to fetch (default 100, max 1000) |
instance | Filter to a specific instance ID |
after | ISO 8601 timestamp — only entries after this time |
before | ISO 8601 timestamp — only entries before this time |
level | Minimum level: trace, debug, info, warn, error |
raw | If true, returns full JSON entries instead of conversation view |
Resources
The MCP server also exposes agent SKILL.md files as resources at al://agents/{name}/skill. This lets Claude Code read the full instructions for any agent without going through the filesystem.
CLI commands
al mcp serve
Starts the MCP stdio server. This is what Claude Code spawns as a subprocess — you don’t typically run it directly.
al mcp serve
al mcp serve -p ./my-project
al mcp serve -E production
| Option | Description |
|---|
-p, --project <dir> | Project directory (default: .) |
-E, --env <name> | Environment name — routes gateway calls to a remote environment |
-E flag, then AL_ENV env var, then .env.toml’s environment field. If your project is bound to a remote environment, MCP tool calls go to the remote gateway automatically.
al mcp init
Writes (or merges into) .mcp.json in the project root so Claude Code discovers the MCP server automatically.
al mcp init
al mcp init -p ./my-project
| Option | Description |
|---|
-p, --project <dir> | Project directory (default: .) |
.mcp.json already exists, merges the action-llama entry into the existing mcpServers object. If an action-llama entry already exists, it is overwritten.
al claude init
Scaffolds Claude Code slash commands into .claude/commands/ in the project directory. Existing command files are not overwritten.
al claude init
al claude init -p ./my-project
| Option | Description |
|---|
-p, --project <dir> | Project directory (default: .) |
See Also