Getting started

Core concepts

The building blocks of LoCrew and how they relate: agents, runtimes, conversations, channels, direct messages, runs, chains, hand-offs, sessions, flows and limits.

LoCrew has a small vocabulary. Most confusion comes from mixing up four of these words: agent, conversation, run and session. This page explains each one and how they fit together.

#How LoCrew works

text

             ┌──────────── your computer ────────────┐
  You ──►    │  LoCrew app                           │
             │   ├─ conversations (channels, DMs)     │
             │   ├─ orchestrator: who runs, when      │
             │   ├─ gateway: LoCrew's own tools       │
             │   └─ SQLite database, encrypted keys   │
             │                                        │
             │  Runtimes: Claude Code, Codex CLIs ────┼──► Anthropic / OpenAI
             │            local model server          │
             └────────────────────────────────────────┘
               model providers, A2A agents ◄── over the network

You post a message in a conversation.
The orchestrator decides which agents it wakes (everyone in a DM; only @mentioned members in a channel), queues their runs, and enforces your limits.
Each run goes to the agent's runtime, which does the thinking, resuming the agent's session for that conversation where it has one.
Agents can call LoCrew's own tools through a local gateway, for example send_message to hand work to another agent.
Replies, hand-offs and activity land back in the shared transcript.

#Glossary

Term	Meaning
Agent	A configured teammate: name, role, instructions, runtime, permissions. See Agents.
Runtime	What does an agent's thinking: Claude Code, Codex, a model from an AI provider, or an external A2A agent. See Runtimes.
AI provider	A connected source of models: a hosted API, an OpenAI-compatible server, or a local model server.
Conversation	Any place messages are exchanged. Channels and direct messages are both conversations.
Direct message (DM)	You and one agent. Every message wakes it.
Channel	You and several agents. Only @mentioned agents are woken.
Mention	`@name` in your message. Decides who is woken. `@all` addresses everyone in the channel.
Run	One piece of work by one agent, started by a message, a hand-off or a flow step. Also called an execution.
Chain	All the runs that follow from one message you send, including hand-offs. Limits on hops and spend apply per chain.
Hand-off	One agent waking another by calling `send_message`. Never by writing a name. See Agent hand-offs.
Session	A runtime's memory of one agent in one conversation. See Sessions.
Work session	Temporary permission for an Ask first agent to write without asking. Unrelated to runtime sessions.
File access level	Read only, Ask first or Full access: what a Claude Code or Codex agent may change.
MCP server	A tool server speaking the Model Context Protocol. Its tools are granted to agents one by one.
Gateway	LoCrew's own local tool server that agents use to post messages, read the conversation and update tasks.
Flow	A repeatable process drawn as a graph of steps. See Flows.
Step	One box in a flow: a start, an agent, an HTTP request, a message, a condition, an approval or a join.
Flow run	One execution of a flow, recorded step by step.
Limits	Global safety rails on hops, queues, run time and spend. See Limits.

#Agent, conversation, run and session

Take one agent, Developer on Claude Code, that is in its own DM and in two channels, #backend and #frontend.

	How many	Why
Agents	1	Developer is configured once. Its name, instructions and permissions are the same everywhere.
Conversations	3	Its DM, `#backend` and `#frontend`.
Sessions	Up to 3	One per conversation, created on its first run there. What it learns in `#backend` does not leak into `#frontend`.
Runs	One per time it is woken	Each message or hand-off that wakes it starts a run, in that conversation. It can work in two conversations at once, but only one run at a time in each.

#Conversations and flows

Conversations and flows use the same agents with the same permissions. Use a conversation when the work is open-ended and the agents decide how to proceed. Use a flow when the process should always follow the same shape. A flow can be started from a conversation with /run and post its result back there. See Introduction to Flows.

#What LoCrew guarantees, and what it does not

Agents are woken only by your messages, by send_message hand-offs within your limits, or by flow steps.
Hand-offs are attributed by a per-run token, not by what an agent writes.
File access levels and approvals are enforced through each CLI's own permission system. They are limits, not a sandbox: the CLI runs as your user account.
Spend limits only see runtimes that report a price (Claude Code and Codex).