Assistants

An Assistant is a persistent AI companion that lives in your Agor workspace. While a normal worktree is where code gets written, an Assistant is a who — a persistent entity with memory, skills, and the ability to orchestrate work across your entire workspace.

The assistant framework is heavily inspired by OpenClaw, a proven pattern for building persistent AI agents with file-based memory and identity. Agor’s implementation adapts the core ideas — markdown-based memory, identity files, and scheduled loops — while making the assistant deeply aware of its environment through Agor’s MCP tools. An Agor assistant can create worktrees, spawn sessions, manage boards, and coordinate multi-agent workflows — capabilities that go well beyond the original pattern.

Framework repository: github.com/preset-io/agor-assistant

How it works

An Assistant is a special worktree backed by the framework repository — a template repo containing memory files, identity configuration, skills, and task templates. When you create an assistant, Agor:

1. Forks the framework repo into a new worktree
2. Tags the worktree with assistant metadata (name, framework version)
3. Creates a dedicated board for the assistant’s work
4. Launches your first session — triggering BOOTSTRAP.md

From there, every session in that worktree picks up the assistant’s accumulated memory and context.

Key concepts

BOOTSTRAP.md — First boot

When an assistant is created for the first time, it runs through BOOTSTRAP.md — the initialization script that sets up identity, preferences, and initial state. This is where the assistant introduces itself, learns about you, and configures its working environment. Think of it as the assistant’s “first day” checklist.

Memory across sessions

Assistants maintain file-based memory in their worktree. Memory is organized into two layers:

Identity files (root of the worktree):

• SOUL.md — Personality, communication style, core principles
• IDENTITY.md — Who the assistant is, its name, and purpose
• USER.md — Knowledge about you, your preferences, and patterns

Daily memory (memory/ directory):

• memory/{YYYY-MM-DD}.md — Daily journal entries. Each day the assistant works, it appends observations, decisions, and learnings to that day’s file. This creates a chronological, searchable record of everything the assistant has done and learned.

Each new session reads the identity files and recent memory, giving the assistant continuity across conversations. As the assistant works, it updates these files — building a richer understanding over time. All memory is plain markdown — fully inspectable, editable, and version-controlled.

BOARD.md — Resident board semantics

Every assistant has a BOARD.md file that describes the semantics of its main (resident) board. This file tells the assistant what each zone on the board means, how worktrees should be organized spatially, and what the overall layout represents. When the assistant creates or moves worktrees on its board, it refers to BOARD.md to understand the intended structure — ensuring consistent spatial organization across sessions.

HEARTBEAT.md — Scheduled tick workflows

HEARTBEAT.md contains the instructions and workflows the assistant processes every time a scheduled tick occurs. Think of it as a flowchart in pseudo-code: a set of steps the assistant follows on each heartbeat, such as:

• Check the status of in-progress worktrees
• Review BOARD.md to assess spatial organization
• Look for new issues or PRs to triage
• Summarize progress to daily memory (memory/{YYYY-MM-DD}.md)
• Start new work based on priorities

Configure heartbeat frequency through Agor’s scheduler — from every few minutes to once a day.

Skills

Assistants aren’t limited to code generation — they can be equipped with skills that extend their capabilities through tools, APIs, and integrations. Skills are defined in the framework repo and give your assistant the ability to interact with external systems.

Examples of what skills enable:

• SaaS integrations — Query Jira for open tickets, post updates to Linear, fetch metrics from Datadog or PagerDuty
• Communication — Send Slack messages, create GitHub issues, post comments on PRs
• CLI tools — Run linters, test suites, deployment scripts, or any command-line tooling in your stack
• REST APIs — Call internal or external APIs to fetch data, trigger webhooks, or sync state
• MCP servers — Connect to any MCP-compatible service for specialized capabilities (databases, cloud providers, monitoring systems)

Skills make assistants practical for real workflows — not just coding, but the coordination and communication around it.

Workspace orchestration

Through Agor’s MCP tools, assistants can:

• Create worktrees — Spin up new isolated work environments for specific tasks
• Spawn sessions — Delegate work to child sessions with focused prompts
• Manage boards — Organize worktrees across spatial canvases (guided by BOARD.md)
• Check on work — Review session status, read files, assess progress

This makes assistants natural orchestrators — they can break down complex tasks, distribute work across multiple worktrees, and synthesize results.

Learning and adaptation

As your assistant works with you, it naturally improves:

• Learns your coding patterns and preferences (stored in USER.md)
• Understands your repository structure and conventions
• Builds knowledge about your team’s workflows (daily memory)
• Adapts its communication style to match yours (refined in SOUL.md)

Creating an assistant

From the onboarding wizard

When you first log into Agor, choose “Set up your assistant”. The wizard will:

1. Clone the assistant framework repository
2. Create a personal board
3. Set up a worktree with your own branch
4. Configure API keys
5. Launch your first session (which runs BOOTSTRAP.md)

From Settings

Go to Settings > Assistants > Create Assistant:

1. Enter a display name (e.g., “PR Reviewer”, “Command Center”)
2. Choose or create a board
3. Optionally customize the framework repo and branch
4. Click Create

From the CLI

During agor init, you’ll be prompted to set up an assistant. This queues the setup for the UI wizard on your next login.

Assistant vs. Agent

These terms mean different things in Agor:

An assistant uses an agent to do its work. When you create a session for your assistant, you choose which agent runs it (Claude Code is the default).

Think of it this way:

• “Start my assistant” = open a session on your persistent AI companion’s worktree
• “Choose an agent” = pick which AI model/tool runs that session

Managing assistants

Settings > Assistants

The Assistants table in Settings shows all your assistants with:

• Display name and worktree name
• Environment status (start/stop controls)
• Framework repository
• Branch and session count

WorktreeModal > Assistant tab

Click any assistant’s worktree card to open its modal. The Assistant tab shows:

• Editable display name
• Framework repo and version
• Creation method (onboarding vs manual)

Boards

Assistants appear as worktree cards on boards, distinguished by a robot icon and blue border. We recommend giving each assistant its own board for clarity.

Real-world examples

For real-world use cases and the story behind Agor Assistants, see our blog post: Introducing Agor Assistants.