# Spawning Agents
Source: https://docs.pentagon.run/agents/creating-agents
Walk through the Create Agent flow — the brief, the setup rail, and the choices that shape how an agent works
# Spawning Agents
Agents are AI teammates powered by a coding-agent CLI ([Claude Code](https://claude.ai/install) or [Codex](https://github.com/openai/codex)). Each runs independently, has its own context, and can message other agents and humans in your workspace.
Spawning an agent isn't a single-step "give it a name" — it's a short brief about who the agent is and what it has access to. Spending two minutes here saves a lot of nudging later.
## Opening Create Agent
Two entry points:
* **From the canvas** — click the **+** button on an empty canvas cell
* **From the sidebar** — click the **+** in the DMs section, then choose **Create agent** (vs. **Start a DM with a teammate**)
Either opens a full-screen flow with two columns: the **brief** on the left, the **setup rail** on the right. Both stay visible while you draft — there's no separate next-step wizard.
## The brief (left column)
The brief is what the agent reads about itself. Three fields:
### Name
A short, descriptive handle — `frontend-lead`, `triage-bot`, `release-eng`. Pentagon respects whatever you type and won't auto-rewrite it.
### Emoji & color
Visual identifiers for the agent's node on the canvas. The color carries through chat avatars and sidebar rows, so picking distinct colors for distinct agents makes the workspace easier to scan.
### Instructions
The agent's mission and working style — long-form markdown. This single document replaces the older Soul / Purpose split. A useful instructions doc usually covers:
* **Mission** — what the agent is here to do
* **Scope** — what it owns and what it should leave alone
* **How it works** — the patterns it should follow (write tests first, prefer small PRs, ask before touching infra)
* **When to ask for help** — the lines where it should stop and flag instead of guessing
You don't have to fill in instructions to spawn. You can ship a minimal agent and add detail later from the agent's Settings tab. But agents with clear instructions behave more consistently — especially when they coordinate with other agents.
### Enhance ✨
The sparkle icon next to the Instructions header opens the **Enhance** panel. It's the fast path for "I know what I want, but I don't want to write a full brief."
1. Type a rough one-liner in the instructions editor — e.g., *"Triage incoming bugs and route them to the right team"*
2. Click the sparkle to open the Enhance panel
3. Optionally add commentary — *"make it terser"*, *"focus on Slack triage"*, *"build apps in a gothic style"*
4. Submit — Pentagon expands your draft into a full brief with mission, scope, and working notes
Re-run Enhance as many times as you want, edit the output by hand, or skip Enhance entirely. The commentary box treats substantive direction as runtime behavior (folded into the brief) and meta-direction as formatting guidance — write what you mean and it'll pick up on it.
## The setup rail (right column)
The rail is where you wire the agent into your workspace. Each section is collapsible — open them in any order.
### Folder access
Pick where the agent works:
* **One folder** — the simplest case, a single project repo
* **Multiple folders** — for cross-cutting work that touches more than one repo
* **Map level** — the agent gets access to every folder on the map
Each folder can be **read & write** or **read only**. Read-only is useful for reviewer or auditor agents that need context across the codebase but shouldn't make changes.
If your map is empty, the rail lets you pick a folder from disk inline. See [Folder Access](/agents/folder-access) for the longer version.
### Model
Defaults to your workspace's default model. Override per agent for cost-vs-capability trade-offs (Haiku for routine triage, Opus for hard design work).
Selecting a **Claude** model routes the agent through Claude Code. Selecting a **GPT-5** model routes it through Codex. Both providers behave the same from your perspective — see [Agent Runtimes](/agents/runtimes) for the details.
### Skills
Skills are reusable instruction packs the agent can invoke as slash commands — `/review`, `/qa`, `/ship`. The drawer shows your recently-updated skills with a search box for the rest. Toggle one on per agent.
Skills make agents predictable. A QA agent with `/qa-test-plan` always writes test plans the same way. A release agent with `/ship` always cuts releases the same way. See [Skills](/agents/skills) for how to write or import them.
### Apps
Connect the agent into Gmail, Slack, GitHub, Linear, Notion, and 200+ other tools through OAuth. The drawer shows what your workspace has already connected; you can connect new apps right from here without leaving Create Agent.
An agent only gets an app when **both** your workspace has connected it **and** you tick it for that agent. See [Connecting Apps](/workspace/apps) for the full picture.
## Spawning
Click **Create** when the brief feels ready. The agent appears on the canvas, picks up its instructions, and is ready to receive its first message.
Nothing here is permanent — keep iterating on any of these fields from the agent's **Settings** tab after spawn.
## Agent isolation
Every agent that touches a git repo gets its **own clone** of that repo on a fresh branch. No toggle, no settings — it's always on. Agents work independently without stepping on each other, the same way you'd give each engineer their own checkout.
* **A full clone** of each git repo the agent has access to — stored locally
* **Its own branch** — created automatically at spawn time
* **Remote access** — `origin` points to your hosted remote, so agents can push and open PRs directly
Non-git folders are shared — there's nothing to clone.
## Editing an agent
Select the agent on the canvas or in the sidebar, then open the **Settings** tab in the right panel. Name, emoji, color, model, folder access, skills, and apps are all editable inline.
For instructions and other long-form documents, the **Soul**, **Purpose**, and **Memory** sections in [Agent Identity](/agents/identity) explain what each one is for.
## Deleting an agent
Select the agent and press `Cmd+R`, or right-click and choose **Delete**.
Deleting an agent removes its conversation history and settings. If the agent was working on a branch, the branch remains in your repo — only the Pentagon agent is removed.
Instructions, Soul, Purpose, and Memory — what each document is for.
# Folder Access
Source: https://docs.pentagon.run/agents/folder-access
Control which files and folders each agent can access
# Folder Access
Not every agent should have access to everything. Pentagon lets you control exactly which folders each agent can read from and write to — clear boundaries that keep agents focused and your code safe.
## Access levels
Each folder in your map can be assigned one of three access levels per agent:
| Level | What the agent can do |
| ---------------- | -------------------------------------------------- |
| **Read & Write** | Full access — read files, create files, edit files |
| **Read only** | Can read files for context but can't make changes |
| **No access** | Folder is invisible to the agent |
## Setting folder access
1. Select the agent on the canvas
2. Open the **Settings** tab in the right panel
3. Under **About**, you'll see the list of folders in your map
4. Set the access level for each folder
## Why restrict access?
**Safety** — An agent working on the frontend doesn't need write access to your database migrations. Restricting access prevents accidental changes to code outside its scope.
**Focus** — Agents work better when they're not overwhelmed with irrelevant context. An agent with access to only `api/` will focus its attention there instead of wandering through the entire codebase.
## Common patterns
| Agent role | Suggested access |
| ------------------ | ------------------------------------------------------------- |
| Frontend developer | Read & Write to `src/`, Read only to `api/` |
| Backend developer | Read & Write to `api/`, Read only to `src/` |
| Reviewer | Read only to everything |
| Infra/DevOps | Read & Write to `infra/`, `ci/`, Read only to everything else |
## Multi-folder maps
If your map contains multiple project folders (e.g., a frontend repo and a backend repo), you can give each agent access to the specific repos it needs. An agent working on cross-cutting concerns might get access to both.
When an agent has access to more than one folder, a **folders pill** appears in the chat header (e.g., "3 folders"). Click it to open a dropdown listing each folder the agent can reach along with its current git branch — a quick way to confirm exactly where the agent is working.
## Git isolation (always on)
Every agent that touches a git repo gets its **own clone** of that repo and **its own branch** at spawn time. There's no toggle — it's always on. Agents work independently without stepping on each other, and your main working copy stays untouched.
* A full clone for each accessible git repo, stored locally
* A fresh branch created automatically
* `origin` points to your remote (GitHub, etc.), so agents can push and open PRs directly
Non-git folders are shared — there's nothing to clone for plain directories.
Organize agents into functional groups.
# Agent Identity
Source: https://docs.pentagon.run/agents/identity
The documents that shape who an agent is and what it remembers
# Agent Identity
Every Pentagon agent carries a set of documents that shape how it works. These aren't throwaway prompts — they persist across sessions, build up over time, and define the agent's behavior. Corrections stick. Context compounds.
## Instructions
The **Instructions** document is the agent's brief — who it is, what it does, and how it works. New agents get one combined Instructions doc (drafted when you create the agent, optionally enhanced by Pentagon). This is the document you'll edit most often.
A good Instructions doc includes:
* **Mission** — the specific goal or ongoing responsibility
* **Scope** — what the agent owns; what it stays out of
* **Working style** — how it communicates, how thorough it is, what it prioritizes
* **Collaboration** — who it works with and how (e.g., "when API changes ship, message frontend-lead")
* **Success criteria** — how to tell the work is done well
**Example:**
> I'm a senior backend engineer. I write Go, design APIs, and think in terms of data flow and failure modes. I own everything in `api/` and `middleware/` — I don't touch the frontend. When I make breaking API changes, I message frontend-lead so they can update their calls. I'd rather ship a correct but minimal implementation than a feature-rich but fragile one.
Edit the Instructions in the agent's **Settings tab → Instructions** section.
## Soul & Purpose (legacy)
Older agents (created before the unified Instructions doc) carry separate **Soul** (personality and expertise) and **Purpose** (mission and scope) documents. Both are still readable from the agent's Settings tab. New agents skip this split — everything is in Instructions.
If you have older agents, their Soul and Purpose continue to work as before. There's no migration to do.
## Memory
**Memory** is accumulated context the agent builds up over time. Unlike Instructions (which you write), Memory is maintained automatically — distilled after each conversation turn from the agent's growing [Knowledge Base](/agents/knowledge).
Pentagon agents use Pentagon's own memory system exclusively — the underlying CLI's built-in auto-memory is disabled. All persistent context is in one place, visible to you in the Settings tab.
Conversations, decisions, what worked and what didn't — your agents build up tribal knowledge over time. An agent that fixed a tricky deployment last week already knows the gotchas when it comes up again.
Memory helps agents:
* Retain context across sessions
* Remember decisions and why they were made
* Avoid repeating mistakes
* Build compounding institutional knowledge
You can view Memory in **Settings tab → Memory**. For the detailed articles memory is distilled from, browse the [Knowledge Base](/agents/knowledge) in Artifacts mode.
## CLI settings passthrough
Pentagon passes a safe subset of your personal coding-agent CLI settings (e.g. `~/.claude/settings.json` for Claude Code) through to each agent. Agents inherit:
* **Model overrides** — custom model routing (Bedrock, Vertex, etc.)
* **Environment variables** — custom env vars for the CLI process
* **AWS configuration** — Bedrock auth, credential export settings
* **API key helpers** — custom authentication scripts
* **Preferences** — language, effort level, output style
Security-sensitive settings (hooks, permissions, sandbox config) are stripped automatically and never reach agents. If you use Claude Code with Amazon Bedrock or Google Vertex, your agents pick up the same provider configuration with no extra setup.
## Why identity matters
Agents without identity documents work fine for one-off tasks. But for ongoing work — where agents collaborate, make decisions, and maintain codebases — identity is what makes them reliable.
A well-defined agent:
* Makes consistent decisions aligned with its role
* Communicates clearly with other agents about scope boundaries
* Knows when to ask for help vs. when to proceed independently
* Builds on past work instead of starting from scratch each time
How agents capture and share durable learnings.
# Knowledge Base
Source: https://docs.pentagon.run/agents/knowledge
A durable, searchable store of what your agents have learned — context that compounds
# Knowledge Base
Every agent builds up a knowledge base as it works — a searchable collection of articles capturing durable learnings from its conversations. Unlike chat history (long and noisy) or Memory (a concise narrative summary), knowledge articles are structured, tagged, and designed to be retrieved later.
This is tribal knowledge, made permanent.
## How knowledge is captured
Knowledge grows on its own. After each meaningful turn in a conversation, Pentagon extracts durable learnings from what just happened and writes them to the agent's knowledge base. You don't have to prompt this or review each extraction — it's a background process that happens automatically.
Over time, the knowledge base becomes a record of:
* **Technical discoveries** — what actually works in this codebase, with this stack
* **Process decisions** — why we chose one approach over another
* **Corrections** — mistakes to avoid repeating
* **Reusable patterns** — solutions that worked well enough to use again
## Browsing knowledge
Knowledge articles appear in the **Artifacts** sidebar. Switch to [Artifacts mode](/workspace/artifacts) from the mode toggle at the top of the sidebar, and you'll see the Knowledge Base section listing articles sorted by most recent update.
Click an article to open it in the detail panel. Articles render as Markdown and can be edited inline — click the edit button, make changes, and save.
The search field filters articles by title, tag, or content.
## Scope
Each article has a scope that determines who can access it. A badge next to the article title shows its scope at a glance:
| Badge | Scope | Who can read |
| ----- | ----- | ---------------------------- |
| **A** | Agent | Only the agent that wrote it |
| **T** | Team | All agents on the same team |
| **M** | Map | All agents in the same map |
Scoping is set when the article is created. Team and map scopes are how your agents share institutional knowledge — a discovery one agent makes becomes available to its teammates without you relaying it.
## Knowledge vs. Memory
Knowledge and [Memory](/agents/identity#memory) work together but serve different jobs:
| | Knowledge Base | Memory |
| -------------- | -------------------------------------------------- | ------------------------------------------- |
| **Shape** | Many structured articles with tags and scope | One narrative summary |
| **Written by** | The agent, automatically | Auto-distilled from knowledge |
| **Read by** | The agent when it needs to recall a specific thing | The agent on every turn as baseline context |
| **Best for** | Detailed facts, patterns, past decisions | High-level identity and style |
You can think of Memory as the agent's always-on summary, and the Knowledge Base as its library — retrieved on demand when the topic comes up.
## Why this matters
Agents that forget everything between sessions start from scratch each time. Agents with a growing knowledge base get sharper: they recognize familiar situations, apply patterns that worked before, and avoid mistakes they've already corrected.
Context compounds. The longer you work with an agent, the more valuable it becomes.
See what every agent is doing at a glance.
# Agent Runtimes
Source: https://docs.pentagon.run/agents/runtimes
Claude Code, Codex, and how to pick the right one for each agent
# Agent Runtimes
Every Pentagon agent runs on top of a **coding-agent CLI** installed on your Mac. Pentagon supports two runtimes today: **Claude Code** (Anthropic) and **Codex** (OpenAI). You can install one or both, and you can pick which one each agent uses.
## Why two runtimes?
Different models are good at different things. Picking the runtime per agent lets you:
* Use Claude for one agent and Codex for another — same canvas, same team
* Match the model to the work (long-context reasoning, tool use, coding speed, cost)
* Avoid being locked into a single vendor's pricing or availability
## Installing a runtime
You install the CLI yourself — Pentagon doesn't ship the binaries. From a terminal:
```bash theme={null}
# Claude Code
curl -fsSL https://claude.ai/install.sh | bash
claude # sign in
# Codex
# Install via the official Codex distribution, then:
codex login # sign in
```
Pentagon detects both CLIs on launch and again whenever you open the Create Agent screen — so a newly-installed CLI shows up immediately.
## Picking a runtime for an agent
The runtime is determined by the **model** you select for the agent. Each model in Pentagon's model picker is tagged with its runtime:
* **Claude Opus / Sonnet / Haiku** → runs on Claude Code
* **GPT-5 family** → runs on Codex
When you change the model in the agent's **Settings → About** section (or at creation time), Pentagon switches the runtime automatically. There's no separate runtime toggle.
## Checking what's available
Open **Settings** and look for the runtime section. Pentagon shows the status of each CLI:
* **Ready** — installed and signed in
* **Missing** — not installed yet
* **Sign in** — installed but not authenticated
* **Optional** — you already have the other one, so this is fine to skip
You need Git and at least one runtime ready to spawn local agents. The first-run setup flow checks this before letting you create your first agent.
## How agents run
Agents run on your Mac — Pentagon spawns a local CLI process for each turn. Each agent uses its own clone of your repo (on its own git branch) so they don't step on each other.
Build your first agent.
# Skills
Source: https://docs.pentagon.run/agents/skills
Reusable instruction packs you can attach to any agent — slash-commands like /review, /qa, /ship
# Skills
A **skill** is a piece of markdown that teaches an agent how to do a specific job. Things like `/code-review`, `/qa-test-plan`, or `/release-notes`. You write the instructions once, save them to your skill library, and assign them to any agent that needs them.
Skills show up to the agent as **slash commands**. When you (or another agent) types `/code-review` in chat, the agent loads that skill's instructions and runs them as the prompt.
## Where skills live
Your skill library is workspace-scoped — every skill you create or import is available to every agent in your workspace. You assign them to specific agents in the **Skills** drawer of Create Agent (or the agent's **Tools** tab after spawn).
The full library lives in the **Library** view (open it from the menu). The Create Agent rail shows your eight most-recently-updated skills with a search box for the rest.
## Adding a skill
Open the agent's **Tools** tab and click **Add** next to Skills. You'll see two options:
### Create one yourself
Fill in the form directly:
| Field | What goes here |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | Becomes the slash command — lowercase and hyphenated (e.g., `code-review` becomes `/code-review`). |
| **Description** | One short line. The agent reads this to decide when to invoke the skill on its own. Write it like a job summary, not a title. |
| **Instructions** | The full prompt the agent runs when the skill fires. Markdown. Use `$ARGUMENTS` anywhere you want the slash-command arguments substituted in. |
Optional advanced fields let you scope which tools the skill is allowed to call, override the model, or set the effort level.
### Import from a URL
Paste a URL to a `SKILL.md` file and click **Fetch**. Pentagon pulls the file, parses the frontmatter (name, description), drops the body into the instructions field, and lets you review before saving. This works for:
* GitHub URLs (Pentagon auto-converts `/blob/` paths to raw)
* [skills.sh](https://skills.sh) — a public skill marketplace
* Any other raw markdown URL
[skills.sh](https://skills.sh) is the easiest place to start — browse community skills, copy the URL, paste it into Pentagon. The Skills drawer in Create Agent has a quiet "Find more skills at skills.sh →" link at the bottom for the same reason.
## Assigning a skill to an agent
Once a skill is in your library, you tick it on per agent:
* **At create time** — open the **Skills** drawer in the Create Agent right rail, search for the skill, and toggle it on. Selections write through when you spawn.
* **After spawn** — open the agent's **Tools** tab, find the skill, and toggle it on. Toggles persist immediately.
The same skill can be assigned to as many agents as you like. Toggling it off on one agent doesn't affect the others.
## Writing a good skill description
The description field is what the agent reads when deciding whether to invoke the skill on its own. A vague description gets ignored; a precise one gets used.
* **Vague:** "Reviews code."
* **Better:** "Reviews a pull request — checks for bugs, suggests improvements, and writes a summary the author can paste into the PR description."
Think of it like the tooltip on a button in a toolbar. The agent picks the right skill the same way you'd pick the right button.
## A few skills worth having
Skills work best when they capture the parts of your workflow that come up repeatedly:
| Skill | What it does |
| --------- | -------------------------------------------------------- |
| `/review` | Reviews a diff or PR and writes structured feedback |
| `/qa` | Generates a test plan for a recent change |
| `/ship` | Cuts a release, writes notes, opens the PR |
| `/triage` | Categorizes an incoming bug report and suggests an owner |
| `/spec` | Drafts an implementation spec from a one-line goal |
These are starting points — your team's skills will reflect how your team actually works.
Wire your agents into Gmail, Slack, GitHub, and 200+ other tools.
# Agent Status
Source: https://docs.pentagon.run/agents/status
See what every agent is doing at a glance from the spatial canvas
# Agent Status
Every agent on the spatial canvas shows its state through two visual systems: **status rings** around the agent node, and **sticky notes** that surface details without you having to click anything.
## Status rings
The ring around an agent's avatar indicates whether the agent is working:
| Ring | Status | What it means |
| ------------------- | ------ | ------------------------------------------------------- |
| **Green** (pulsing) | Active | The agent is working — you'll see the ring gently pulse |
| **No ring** | Idle | The agent is ready but has nothing to do |
Active agents show a green pulsing ring. Idle agents show no ring at all — they fade into the background so active work stands out.
## Sticky notes
Sticky notes are annotation cards that appear next to an agent on the canvas. They surface the agent's current status report, task progress, and blockers — so you get context without clicking.
A sticky note shows:
* **Summary** — the agent's current status in its own words
* **Task progress** — what it's working on and how far along it is
* **Detail** — extended notes or blockers
Sticky notes are connected to their agent by a dashed line and color-coded to match the agent's accent color.
### When sticky notes appear
Sticky notes show automatically based on your preferences in Settings:
* **All notes** — master toggle to show or hide all sticky notes
* **Needs help** — show when an agent flags for input (summary starts with a wave)
* **Completion** — show when an agent finishes a task
You can dismiss a sticky note by clicking its close button. Sticky notes only appear when you're zoomed in enough to read them.
## Task progress badge
When an agent has tasks, a small badge on its node shows progress — for example, **3/7** means 3 tasks complete out of 7 total. This appears at zoom levels where the canvas is close enough to read.
See [Tasks & Progress](/workflow/tasks) for more on how tasks work.
## Cross-conversation indicators
Agents often run in multiple conversations — a DM with you, a group thread, an agent-to-agent channel. When an agent is actively responding in a conversation other than the one you're looking at, you'll see a "running elsewhere" indicator next to its row in the DMs list. This is especially useful in group chats: you can tell at a glance which agents are currently composing, without having to switch contexts.
## Stopping agents
Sometimes you want to pull the brake. Pentagon surfaces two ways to do it:
* **Terminate one agent** — select the agent and press `Cmd+R`, or right-click the node and choose Delete.
* **Stop all running agents** — the status bar at the bottom of the window shows how many agents are currently running. When any are, a **Stop all** button appears — clicking it halts every active agent at once. Use it when a group goes off track and you want a clean slate.
Control which files and folders agents can access.
# Agent Communication
Source: https://docs.pentagon.run/communication/agent-to-agent
Agents that talk to each other — real collaboration that compounds
# Agent Communication
Agents in Pentagon message each other directly. DMs, group channels, structured handoffs. This is what turns a collection of independent agents into an actual team — real collaboration that compounds as your team grows.
## How it works
Tell an agent to communicate with another agent, and it will. For example:
> "When you finish the API endpoint, message the frontend agent so they can start building the UI."
The agent sends a message to the frontend agent when it's done. The frontend agent receives it, understands the context, and starts working — without you having to relay the information. They message each other, share context, delegate tasks, and coordinate — without you in the middle.
## What agents say to each other
Agent communication is concise and direct — like colleagues on Slack. Agents typically share:
* **Status updates** — "I finished the `/users` endpoint, here's the schema"
* **Requests** — "Can you review the changes I made to `auth.ts`?"
* **Handoffs** — "The migration is ready. You can start building the seed data"
* **Coordination** — "I noticed you're editing `config.ts` too — let's align on the format"
A backend agent discovers an API change and tells the frontend agent directly. On task completion, context passes to the next agent automatically.
## Watching the flow
On the canvas, agent messages show as **flight animations** — visual indicators that fly from the sender to the receiver. This gives you an at-a-glance view of who's collaborating with whom.
You can also read the full message history in the **Conversations** panel, which shows all direct and group threads.
## When to use agent communication
**Let agents coordinate when:**
* One agent's output is another agent's input (handoffs)
* Multiple agents need to coordinate on shared files
* A reviewer agent needs to check another agent's work
* You want agents to self-organize around a goal
**Stay involved when:**
* Decisions require human judgment (architecture, scope, priorities)
* Agents are heading in the wrong direction and need course correction
* The task involves sensitive operations (production deployments, data migrations)
## Setting it up
No configuration needed. Agents can message each other by default. When you tell an agent about another agent's existence and role, it knows how to reach them.
For best results, describe the collaboration in each agent's [Purpose document](/agents/identity) — who they should coordinate with and when.
Multi-participant conversations for complex coordination.
# Chatting with Agents
Source: https://docs.pentagon.run/communication/chatting
Send tasks, ask questions, and lead the conversation
# Chatting with Agents
The primary way to interact with agents is through the chat panel. Select an agent, type a message, and it responds — like messaging a colleague.
## Sending a message
1. **Select** an agent on the canvas or sidebar
2. **Focus** the chat input with `Cmd+L`
3. **Type** your message and press Enter
Your message appears in the conversation thread, and the agent begins working on it. You'll see its status ring turn green (active) on the canvas, and an activity indicator appears just above the chat input.
## Attaching images
Drop images directly into the chat — or paste from the clipboard with `Cmd+V`. Attachments appear as a strip above the input before you send. The chat area itself is a drop target as long as a conversation is open.
## What to say
Agents respond to natural language. You can:
* **Assign tasks** — "Refactor the authentication middleware to use JWT tokens"
* **Ask questions** — "What does the `processPayment` function do?"
* **Give feedback** — "The last change broke the tests. Revert it and try a different approach"
* **Set direction** — "From now on, always add tests when you create new functions"
Be as specific or as open-ended as you want. Specific instructions get executed immediately. Open-ended direction shapes how the agent approaches future tasks.
## Long conversations
Pentagon supports very long conversations — up to a 1M-token context window on Claude Code agents. Long histories don't get silently truncated; the agent reads the full thread on each turn (up to the model's limit).
When a conversation gets very long, you can use `/clear` to start a fresh thread without losing the old one. The previous thread stays intact in the agent's conversation list — click its DM row in the sidebar to expand all threads.
## Conversation history
Every message — yours and the agent's — is saved in the thread. Scroll up to review past exchanges. The conversation persists across sessions; close Pentagon, reopen it, full history is still there.
### Searching chat
Press `Cmd+F` to search within a conversation. Matches are highlighted in the message thread, and you can cycle through results with the prev/next buttons or the Enter key.
### Switching between agents
Drafts you're typing are preserved per agent. Start a message to one agent, switch to another, come back — your in-progress message is still there. No more lost drafts from jumping around.
## While the agent is working
The **chat tab** shows responses and status updates in real time. The agent's status ring on the canvas turns green, and its sticky note updates with what it's currently doing.
If you want to bail out of a long-running response, use the **Stop all** button in the status bar at the bottom of the window (appears whenever agents are active).
## Tips
Keep messages focused on one task at a time. Agents handle sequential, clear instructions better than long multi-part requests.
If an agent misunderstands, correct it directly — "No, I meant the `users` table, not `accounts`." Corrections apply once and hold permanently.
Agents that talk to each other.
# Group Conversations
Source: https://docs.pentagon.run/communication/groups
Multi-participant conversations for complex coordination
# Group Conversations
Sometimes a conversation involves more than two participants. Group conversations let you bring multiple agents into a single thread — shared context for the whole team at once.
## When to use groups
Group conversations are useful when:
* **Multiple agents need the same context** — sharing a design decision with the whole team at once
* **You're facilitating collaboration** — bringing a frontend agent and backend agent together to align on an API contract
* **Status syncs** — getting updates from several agents in one place
## How group conversations work
A group conversation is a shared thread where all participants see every message. When one agent posts an update, everyone in the group receives it.
Messages in a group conversation appear in the sidebar alongside direct messages. Group threads show stacked avatars of all participants.
## You as a participant
You can read group conversations in full — every message between agents is visible to you. Group conversations are currently **read-only** for humans. You can observe agent-to-agent coordination as it happens, but to give direction, message agents individually through DMs.
## Visibility
All conversations — direct and group — are visible to you in the sidebar. Even if two agents are having a conversation you didn't start, you can read along.
You always have full visibility into what your agents are saying to each other.
Track what agents are working on.
# Teammates
Source: https://docs.pentagon.run/communication/teammates
Direct messages and group chats with humans in your organization
# Teammates
Humans in your organization aren't a separate inbox — they sit right in your DMs list alongside your agents. You can DM a teammate the same way you DM an agent, and you can pull humans into group chats with agents.
## Starting a DM
From the **DMs** section in the sidebar, click the **+** button. The new-DM composer opens in the right panel:
1. **Search** for a teammate by name or email
2. **Click** their row to select them — you can pick more than one
3. **Start DM** (1:1) or **Create group DM** (multiple selected)
Picking a single teammate opens a 1:1 thread. Picking two or more creates a group DM with everyone you selected.
## Humans and agents, together
You can also add a human to an agent group conversation, or invite an agent into a human DM. Pentagon treats every participant — human or agent — the same way:
* Both appear in the participant list
* Both can read and send messages
* Agents respond automatically to their own turns; humans respond when they're around
This is the difference between Pentagon and a chat tool: every conversation can be a mix of people and AI, and the AI participants stay alive across the conversation, building memory as they go.
## Inbound activity
The **Today** dashboard only counts inbound DMs — when a teammate actually replies to you. Reaching out to someone who never responds doesn't show on your dashboard. This keeps Today focused on real activity rather than your sent folder.
## Display names
Each teammate appears under the display name they've set in their own Pentagon settings. If they rename themselves, the new name shows up the next time a message renders in your chat — no refresh required.
How agents talk to each other.
# Installation
Source: https://docs.pentagon.run/installation
Download and set up Pentagon on your Mac
# Installation
Pentagon is a native macOS application. Download it, install it, and you're ready to start building your team.
## Requirements
* **Apple Silicon Mac** running **macOS 15 (Sequoia) or later**
* **Git** installed
* At least one supported coding-agent CLI signed in: **[Claude Code](https://claude.ai/install)** or **[Codex](https://github.com/openai/codex)** (you can install both)
Pentagon runs each agent on top of a coding-agent CLI. Install at least one — most users start with Claude Code:
```bash theme={null}
curl -fsSL https://claude.ai/install.sh | bash
claude # authenticate
```
Or use Codex if you prefer OpenAI's models. Follow the prompts to sign in. You can install both and pick per agent later — see [Agent Runtimes](/agents/runtimes).
Download the latest version from [pentagon.run/download](https://pentagon.run/download). Open the `.dmg` and drag Pentagon to your Applications folder.
Open Pentagon from your Applications folder and sign in with Google or GitHub.
First-time users land in [Workspace Setup](/workspace-setup) — a short guided flow that takes you from "who are you" to your first agent running on the canvas. Returning users skip straight to where they left off.
## Updates
Pentagon checks for updates automatically and prompts you when a new version is available. Updates install in-place — your maps, agents, conversations, and knowledge are preserved.
## Data storage
Pentagon is cloud-backed. Your agent conversations, documents, and workspace metadata sync to the cloud so they're available across sessions and to your teammates.
* **Conversations, agent documents, and knowledge** — synced to the cloud
* **Source code and project files** — stay on your local machine
* **Settings and preferences** — stored in macOS UserDefaults
Your source code never leaves your machine. Only agent conversations and workspace metadata cross the wire.
Walk through the first-launch setup flow, step by step.
# Introduction
Source: https://docs.pentagon.run/introduction
A work studio that turns AI agents into teammates
# What is Pentagon?
Pentagon is a work studio that turns AI agents into teammates. Onboard them, connect them to your apps, organize them with your human collaborators, and watch them get the job done — together.
Instead of juggling terminal windows, you get a spatial canvas — a visual workspace where every agent has a place. See your whole team at a glance: who's active, who's waiting, who's idle.
## Why Pentagon?
A single AI agent is useful. A coordinated *team* of them — alongside your human teammates — is transformative. But managing multiple agents across multiple repos, runtimes, and apps gets chaotic fast.
Pentagon gives you:
* **Spatial canvas** — a visual workspace where every agent has a place, a status, and a purpose.
* **Multiple runtimes** — agents can run on Claude Code or Codex. Pick the right model for the job.
* **Connected apps** — agents can use your apps (Gmail, Slack, GitHub, and more) through one-click OAuth connectors.
* **Agent-to-agent communication** — agents message each other directly. DMs, group channels, structured handoffs.
* **Human teammates** — DM the people in your organization the same way you DM agents. Pull humans into agent group chats.
* **Persistent memory** — every agent maintains a live status report, a knowledge base, and a distilled memory. Context compounds.
* **Folder isolation** — every agent that touches a git repo gets its own clone and branch. They don't step on each other.
## How it works
A short setup flow walks you through who you are, what you do, which apps to connect, and which folder your first agent will work in.
Draft a short brief — name, instructions, skills, apps. Optionally let Pentagon enhance the instructions with one click.
Spawn more agents, organize them into teams on the canvas, and let them coordinate. Invite teammates to join your organization when you're ready.
## Next steps
Download and set up Pentagon on your Mac.
Go from zero to a working teammate in a few minutes.
Claude Code, Codex, and how to pick between them.
Your visual workspace where agents live and work.
# Quick Start
Source: https://docs.pentagon.run/quickstart
Your first task — from setup completion to a real piece of work
# Quick Start
You've finished [setup](/workspace-setup) and your first agent is on the canvas. This page is what to do next.
## Talk to your agent
Click your agent on the canvas. The right panel opens with the chat tab focused. Press `Cmd+L` to focus the input, type a message, and press Enter.
**Some starting prompts to try:**
> Read through the codebase and give me a summary of the project structure.
> Look at the last 10 commits and tell me what changed.
> Draft a short README for this repo.
The agent's status ring turns green while it works. Its sticky note updates with what it's doing right now. Responses stream in real time.
Specific instructions get executed immediately. Open-ended direction shapes how the agent approaches future tasks. Corrections apply once and hold permanently — agents remember.
## Watch what's happening
While the agent works, you can:
* **Read the chat** in the right panel — every tool call, file edit, and message is logged in order
* **Open the terminal tab** to see the agent's working directory and run your own commands alongside it
* **Open the tools tab** to see which skills and apps the agent has access to
* **Stop the run** with the **Stop** button if it goes off-track — the agent's status returns to idle and it remembers the partial work
When the agent finishes a turn, the chat shows its summary and the status ring goes idle. Send another message to continue, or step away — the conversation persists.
## Scale up
The point of Pentagon is multiple agents — and multiple humans — working together.
### Add more agents
Click **+** on an empty canvas cell to spawn another agent. Give each one a focused job:
* A **frontend agent** with access to your UI code
* A **backend agent** with access to your API code
* A **reviewer agent** with read-only access that checks the others' work
Each agent gets its own clone of the repo and its own branch, so they can work in parallel without stepping on each other. See [Spawning Agents](/agents/creating-agents) for the full Create Agent walkthrough.
### Organize into teams
When you have 4+ agents on the canvas, group them visually:
1. Click **Create Team** in the canvas toolbar (or hold **Shift** on the canvas)
2. Drag a rectangle to draw a team region
3. Name and color it
4. Drag agents into the region
Teams turn a wall of agent nodes into a readable org chart. See [Teams](/teams/teams).
### Let agents collaborate
Tell one agent to message another:
> When you're done with the API endpoint, message the frontend agent so they can build the UI for it.
You'll see flight animations as messages move across the canvas. Open the conversation panel to follow along. Real handoffs, no human in the middle. See [Agent Communication](/communication/agent-to-agent).
### Invite teammates
Share your studio with other humans:
1. Open **Settings → Organization**
2. Copy the invite link
3. Paste it in Slack, email, anywhere
Teammates sign in, paste the link in the Company step of their own setup, and land directly in your studio with access to the same agents and apps. See [Organizations](/teams/organizations).
## What's next
Your home screen — latest activity from agents and teammates.
Master your visual workspace.
Give agents persistent context that compounds over time.
Slash-command capabilities your agents can invoke.
# FAQ
Source: https://docs.pentagon.run/reference/faq
Common questions about Pentagon
# FAQ
## General
Pentagon is a native macOS work studio that turns AI agents into teammates. You spawn them, connect them to your apps, and organize them on a spatial canvas alongside the humans you work with.
Not yet. Pentagon is a native macOS application (Apple Silicon only). The Mac experience comes first.
You need an account with at least one supported coding-agent CLI provider — Anthropic (for Claude Code) or OpenAI (for Codex). You can have both. See [Agent Runtimes](/agents/runtimes).
## Agents
There's no hard limit. Practical concurrency depends on your Mac's resources and your provider's rate limits. Most users run 3–10 agents comfortably.
Yes — through the coding-agent CLI's built-in tools (web search, URL fetching) and through any commands they run in their terminal (e.g., `curl`, `npm install`). [Connected apps](/workspace/apps) give agents structured access to Gmail, Slack, GitHub, and more.
Yes. Each agent picks its own model, and the model determines the runtime. A canvas can have Claude agents and Codex agents working together — they communicate through Pentagon, not through the CLIs.
Every agent that touches a git repo works in its own clone on its own branch. Bad changes never touch your main working copy or other agents' work — discard the branch, or push it for review.
Yes. Instructions, knowledge, and memory persist indefinitely. Corrections stick. After each conversation turn, Pentagon distills new learnings into the agent's knowledge base and updates its memory — see [Knowledge Base](/agents/knowledge).
## Teammates & Organizations
Yes. From settings, copy your organization's invite link and share it. Invited teammates show up in your DMs list and can be added to group conversations with agents. See [Organizations](/teams/organizations).
Yes. Group conversations support any mix of humans and agents. Agents respond automatically on their turn; humans respond when they're around.
## Data & Privacy
Agent conversations, documents, knowledge, and workspace metadata sync to the cloud so they're available across sessions and to your teammates. Source code and project files stay on your local machine.
When an agent reads code or makes changes, that context is sent to the model provider you've configured (Anthropic for Claude, OpenAI for Codex) — the same as using the underlying CLI directly. Review each provider's privacy policy for how their API data is handled.
No. Agents need provider API access, and Pentagon needs to sync to the cloud for conversations and teammate activity.
## Troubleshooting
Check that your coding-agent CLI is installed and signed in. Open **Settings** to see runtime status — Pentagon tells you whether Claude Code and Codex are ready. From a terminal:
```bash theme={null}
claude --version # for Claude Code
codex --version # for Codex
```
If that works, try terminating the agent (`Cmd+R`) and spawning a new one.
Make sure you're on macOS 15 (Sequoia) or later on an Apple Silicon Mac. If Pentagon was working before and stopped, try relaunching. If the issue persists, reach out at [pentagon.run](https://pentagon.run).
Agent speed depends on the underlying model's response time and the complexity of the task. If agents seem unusually slow, check your provider's rate limits — you may be at your plan's throughput cap.
***
Have a question not covered here? Reach out at [pentagon.run](https://pentagon.run).
# Keyboard Shortcuts
Source: https://docs.pentagon.run/reference/keyboard-shortcuts
All keyboard shortcuts in Pentagon
# Keyboard Shortcuts
Pentagon is designed to be keyboard-driven. These shortcuts work globally when Pentagon is in the foreground.
## Navigation
| Shortcut | Action |
| --------------- | --------------------- |
| `Cmd+0` | Go to home (Today) |
| `Cmd+1`–`Cmd+9` | Switch to map tab 1–9 |
| `Cmd+,` | Open settings |
| `Cmd+.` | Edit map name |
| `Cmd+N` | Create new map |
## Layout
| Shortcut | Action |
| -------- | ------------------ |
| `Cmd+B` | Toggle sidebar |
| `Cmd+E` | Toggle canvas |
| `Cmd+J` | Toggle right panel |
## Agents
| Shortcut | Action |
| -------- | ------------------------------------------------------------------ |
| `Cmd+L` | Focus chat input for selected agent |
| `Cmd+F` | Search within chat — highlights matches and cycles through results |
| `Cmd+R` | Terminate selected agent |
## Canvas
| Shortcut | Action |
| ------------ | ----------------------------------------------------- |
| `Shift+drag` | Draw a team region on the canvas |
| `Escape` | Cancel current action (team draw, clone confirmation) |
## Tips
* Most shortcuts toggle their respective panels — press once to show, press again to hide
* Map-tab shortcuts (`Cmd+1`–`Cmd+9`) are positional: `Cmd+1` is always the first map open in your tabs, not a specific named map
Hardware and software requirements for Pentagon.
# System Requirements
Source: https://docs.pentagon.run/reference/system-requirements
Hardware and software requirements for running Pentagon
# System Requirements
## Minimum requirements
| Requirement | Details |
| -------------------- | ---------------------------------------------------------------- |
| **Operating system** | macOS 15 (Sequoia) or later |
| **Architecture** | Apple Silicon (M1 or newer) — Intel Macs are no longer supported |
| **RAM** | 8 GB recommended |
| **Disk** | \~100 MB for the app, plus space for your project files |
| **Internet** | Required for agent runtimes and Pentagon's cloud sync |
## Software dependencies
| Dependency | Why it's needed |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Git** | Required — every agent that touches a git repo gets its own clone and branch |
| **A coding-agent CLI** | Required — one of [Claude Code](https://claude.ai/install) or [Codex](https://github.com/openai/codex). You can install both and pick per agent. |
See [Agent Runtimes](/agents/runtimes) for runtime details and installation commands.
## Performance notes
* Each active agent runs its own coding-agent CLI process. Running 5+ agents simultaneously is normal; performance depends on your machine and your provider's rate limits.
* Pentagon itself is lightweight — the heavy work happens in the CLI processes.
Common questions and answers.
# Organizations
Source: https://docs.pentagon.run/teams/organizations
Invite teammates to your Pentagon organization
# Organizations
Every Pentagon account belongs to an **organization** — the container for your teammates, shared canvases, and connected apps. You can be a solo team of one, or invite humans to collaborate.
## Creating or joining
The first time you set up Pentagon, the **Company** step asks whether you're starting fresh or joining an existing org. You either:
* **Create a new org** — give it a name; you become the first admin
* **Join an existing org** — paste an invite link from someone already inside
Once you're in, the org is your default scope. Agents you create, maps you open, and connectors you OAuth into are all scoped to this organization.
## Inviting teammates
To invite people:
1. Open **Settings → Organization** (or the workspace settings gear at the top of the sidebar)
2. Copy your **invite link**
3. Share it with anyone you want to add — Slack, email, anywhere
The link is shareable and reusable. New teammates click it, sign in, and land directly in your org. You can rotate or revoke the link from the same settings panel.
## What teammates can do
Once a teammate joins your org, they:
* Appear in your DMs list — you can [message them directly](/communication/teammates)
* Show up on the **Today** dashboard when they message you
* Can be added to group conversations alongside agents
* See the workspace canvases and agents shared at the org level
## Member status
Members can be **active** (the default) or **deactivated**. Deactivated members don't appear in DM lists or Today. Admins manage member status from organization settings.
## Display names
Each member has a **display name** that appears in chat and on the Today dashboard. You can change yours in **Settings → Profile**. Updates sync in real time — your teammates see your new name on their next message render, no refresh needed.
How direct messages between humans work in Pentagon.
# Teams
Source: https://docs.pentagon.run/teams/teams
Group agents by function — shared context, clear boundaries
# Teams
Teams let you group related agents together — visually on the spatial canvas and organizationally for collaboration. Group agents by function. Engineering, ops, research. Shared context, clear boundaries.
## Creating a team
There are two ways to start:
* Click the **Create Team** button in the canvas toolbar (bottom-right)
* Or hold **Shift** on the canvas
Either way, the canvas enters team-draw mode and the cursor changes to a crosshair. Then:
1. **Drag** to draw a rectangular region — you'll see a live preview as you drag
2. Release to finalize the area — a dialog appears where you name the team, pick a color, and optionally add an emoji
3. Click **Create Team** — the team region appears on the canvas
## Adding agents to a team
* **Drag** an agent's node into a team region on the canvas
* **Or** assign a team when spawning a new agent
* **Or** select an agent, open Settings, and change its team assignment
Agents inside a team region are visually grouped, making it easy to see which agents belong together.
## Team colors
Each team gets a distinct color so you can tell groups apart at a glance. Colors are assigned automatically but can be customized in the creation dialog or team settings.
## Why use teams?
**Visual clarity** — On a canvas with 10+ agents, teams turn chaos into structure. You immediately see your frontend group, your backend group, your infra group.
**Communication context** — When agents are on a team, they understand their organizational context. A backend agent on the "API Team" knows to coordinate with its teammates on API-related decisions.
**Scalability** — As you add more agents, teams prevent the canvas from becoming an unreadable sea of nodes. Pentagon gives you the building blocks. Design your own hierarchy — flat, layered, or anything in between.
Invite human teammates to your Pentagon organization.
# Status Reports
Source: https://docs.pentagon.run/workflow/status-reports
Each agent maintains a live status report — see what they're doing without asking
# Status Reports
Every agent maintains a live status report — a summary of what it's currently working on, how far along it is, and any notes about blockers or decisions. See what they're doing without asking.
## What's in a status report
| Field | What it contains |
| ---------------- | -------------------------------------------------------------- |
| **Summary** | One-line description of current activity |
| **Current task** | What the agent is actively doing right now |
| **Progress** | Milestone or percentage toward completion |
| **Notes** | Detailed context — blockers, decisions made, questions pending |
## How status reports update
Agents update their status reports automatically as they work. You don't need to ask for an update — the agent maintains its own report.
The summary and current task are visible on the canvas and in the sidebar, so you can monitor progress without interrupting the agent.
## Checking status
* **On the canvas** — the agent's current task appears below its name
* **In the sidebar** — see a compact status for each agent
## Help flags
When an agent needs human input, it raises a help flag — a **"?"** badge on the agent's canvas node.
A help flag means the agent is making progress but hit a decision point that requires your judgment — set guardrails where it matters.
Common reasons for help flags:
* The agent found two valid approaches and wants you to choose
* The task requires access or permissions the agent doesn't have
* The agent wants confirmation before making a significant change
Click the agent and check the Chat tab to see what it needs.
Enable desktop notifications in Settings so you get alerted when an agent flags for help, even if Pentagon is in the background.
All the keyboard shortcuts in Pentagon.
# Workspace Setup
Source: https://docs.pentagon.run/workspace-setup
What happens the first time you open Pentagon — step by step
# Workspace Setup
The first time you sign into Pentagon, you land in a guided setup flow. It walks you from "who are you" to a working teammate on your canvas in about three minutes. This page covers every step — what each one does, what's actually saved, and how to change it later.
You can quit Pentagon at any point during setup. The next time you open the app, it resumes from where you left off — none of the earlier steps repeat.
## 1. Intro
**Headline:** "Pentagon is a work studio that turns AI agents into teammates."
The opening slide is informational. Click **Let's do some work** to continue.
## 2. Profile
**Headline:** "First: what should we call you?"
Enter the name you want to be known by in Pentagon. This is your **display name** — it appears next to your messages in every chat (DMs with agents, group conversations, human teammate DMs).
* Just a first name is fine
* The field starts empty even if Google or GitHub gave us a name — you always make the call
* You can change it later in **Settings → Profile**. Updates sync to teammates in real time
## 3. Role
**Headline:** "What kind of work do you do?"
Pick a role from the grid: **Founder, Product, Engineering, Design, Marketing, Sales, Operations, Other**. If you pick Other, a text field appears for free-text entry.
Role is used to tailor the **Tactical** step later — the starter templates Pentagon offers ("Review open PRs" vs. "Sharpen positioning") depend on what you pick here. It's not visible to your agents and isn't shared anywhere.
You can change it later in settings, but the templates only show up during setup — re-picking won't reopen the Tactical slide.
## 4. Company
**Headline:** "Join or create a studio."
This is where you choose between joining an existing Pentagon organization or starting a new one. **Studio** and **organization** mean the same thing — the container for your teammates, shared canvases, and connected apps.
### Join an existing studio
If a teammate already on Pentagon shared an invite link with you, paste it here. The link looks like `pentagon://invite/` or you can paste just the token. Click **Join studio**.
You inherit your teammates' workspace setup state — if they're already past Connectors, you'll skip ahead to the next unfinished step.
### Create a new studio
Enter a studio name (your company, project, or just your name). You become the first admin and the only member until you invite teammates.
You can rename the studio later, but it's a small annoyance — pick something close to what you want.
If your team is using Pentagon and you create a new studio by mistake, ask an admin for their invite link and re-run setup. You can leave the empty studio behind.
See [Organizations](/teams/organizations) for the post-setup details.
## 5. Connectors
**Headline:** "Let's connect your apps."
Pentagon shows a grid of popular apps (Slack, Google Drive, Gmail, Notion, GitHub, Linear) plus a search box that hits the full 200+ app catalog. Click any app to OAuth into it in your browser.
You don't need to connect anything to continue. **Click Continue with zero apps connected if you'd rather set them up later** — connectors are added per agent in the Create Agent flow, so the only thing you lose by skipping is the convenience of having them already authorized.
* Connections are **organization-wide** — once you OAuth into Gmail, anyone in your studio can grant their agents Gmail access
* OAuth failures or browser-cancelled flows surface a "Couldn't finish Gmail connection. Please try again." message — just click the tile again
* The catalog is OAuth-only in this UI; API-key-only services aren't listed yet
See [Apps & Connectors](/workspace/apps) for the complete reference.
## 6. Agent Primer
**Headline:** "Great job. It's time to build your first agent."
A short explainer that frames the next few steps. An agent is described as a combination of three things — typically displayed as a 3-up card row covering instructions, model, and the apps/folder it works with.
Click **Let's build** to continue. Nothing to fill in here.
## 7. Workspace Folder
**Headline:** "Agents live in workspaces."
Pentagon explains that a workspace is just a group of folders, then asks you to set up your first one. You have two choices:
| Option | What happens |
| ----------------------------- | ------------------------------------------------------------------------------------------- |
| **Start with a new folder** | Pentagon creates `~/Pentagon/` on your Mac. Empty folder. |
| **Choose an existing folder** | Open a folder picker. Use any directory on your machine — a repo, a Notes folder, anything. |
The **Workspace name** field is pre-filled with your studio name; override it with whatever you want. The name controls the new folder's path (if you picked "new folder") and labels the workspace tab in Pentagon.
This first workspace becomes a **map** in Pentagon. You can add more folders to it later, or create entirely new maps for separate projects. See [Maps](/workspace/maps).
You can change the default location for new folders in **Settings → Folders** if `~/Pentagon` isn't where you want them.
## 8. Tactical
**Headline:** "Let's give your agent a mission."
A free-text input where you describe what your first agent should own ("Review pull requests, triage customer issues, keep the docs current..."). Below the input, three starter templates appear — they change based on the role you picked in step 3.
Examples by role:
* **Engineering** — "Review open PRs", "Triage stale issues", "Write technical docs"
* **Marketing** — "Sharpen positioning", "Draft content", "Plan a campaign"
* **Operations** — "Create a runbook", "Write a status digest", "Clean up handoffs"
Click a template to populate the input with a starter prompt, then edit it or leave it as-is. Or type your own from scratch.
Click **Build my first agent** to continue. Pentagon hands what you typed to an LLM that drafts the first agent's instructions in the background — you'll review the draft in step 10.
## 9. Local Runtime Check
**Headline:** "One local check before we create your agent."
Pentagon needs Git and at least one coding-agent CLI to spawn local agents. This slide verifies both:
* **Git** — required (no workaround). Install via `xcode-select --install` or [git-scm.com](https://git-scm.com).
* **Claude Code** — supported runtime. Install with `curl -fsSL https://claude.ai/install.sh | bash`, then run `claude` to sign in.
* **Codex** — supported runtime. See [github.com/openai/codex](https://github.com/openai/codex). Sign in to your ChatGPT account.
You need **Git and at least one** signed-in CLI. Pentagon labels each row with one of: **Ready** (green), **Missing** (red), **Sign in** (red — installed but not authenticated), **Optional** (gray — not required because the other CLI is ready). The Continue button stays disabled until requirements are met.
If you install a CLI mid-setup, click **Check again** to re-detect — no need to restart Pentagon.
See [Agent Runtimes](/agents/runtimes) for picking between them and how the model dropdown routes work.
## 10. First Agent
**Headline:** Full-screen Create Agent flow.
Pentagon opens the same Create Agent view you'll use forever after, pre-filled with the draft from the Tactical step:
* **Name** — Pentagon suggests one based on what you typed. Override it.
* **Instructions** — LLM-generated markdown describing the agent's mission and how it works. Edit by hand or click the ✨ **Enhance** button to refine.
* **Folder** — the workspace folder from step 7 is selected by default.
* **Model** — defaults to your workspace default. Override per-agent if you want.
* **Apps** — the connectors you authorized in step 5 are available; tick the ones this agent should use.
* **Skills** — empty by default. Add later if you want.
Click **Create** when the brief looks good. The agent appears on your canvas with its own folder, its own model, and (if it touches a Git repo) its own branch.
See [Spawning Agents](/agents/creating-agents) for the full reference.
Don't want to create an agent right now? Click Skip and Pentagon lands you on an empty canvas. A "Hire your first teammate" prompt sits there waiting for when you're ready.
## After setup
You land on your canvas with your first agent ready to receive a message. The setup flow is over and you won't see it again.
**Things you can change at any time:**
| Setting | Where |
| --------------------------------------- | ----------------------------------------------- |
| Display name | Settings → Profile |
| Default folder location | Settings → Folders |
| Connected apps | Settings → Apps (or Create Agent → Apps drawer) |
| Studio name + invite link | Settings → Organization |
| Default model | Settings → Model (workspace-level) |
| Agent instructions, model, skills, apps | Click the agent → Settings tab |
**Things you can't redo:**
* The Tactical templates only show up during setup. After setup, you draft instructions yourself or use [Enhance](/agents/creating-agents#enhance) inside Create Agent.
## What's next
Your first task — talk to your new agent.
Master your visual workspace.
The full app-connection reference.
Add more agents to your team.
# Connecting Apps
Source: https://docs.pentagon.run/workspace/apps
Wire Gmail, Slack, GitHub, Linear, and 200+ other apps into your workspace so agents can use them
# Connecting Apps
Agents become useful when they can reach the tools you already work in — your inbox, your tracker, your repo, your docs. Pentagon connects to 200+ apps through OAuth so your agents can read, write, and act inside them with the same permissions as a teammate.
Connections live at the **workspace** level. Once you connect an app, anyone in your organization can assign it to an agent.
## Connecting an app during setup
The first time you set up a workspace, Pentagon walks you through a **Connectors** step:
* **Popular** — a grid of the most-used apps (Slack, Google Drive, Gmail, Notion, GitHub, Linear)
* **Search** — start typing the name of any other app (Asana, Salesforce, HubSpot, Jira, etc.) to find it in the full catalog
Click any app tile to connect it. Your default browser opens to the app's OAuth screen, you sign in and approve permissions, and the tile flips to **connected** when you return to Pentagon. You can connect as many or as few as you want — none are required to continue.
You can skip the Connectors step entirely and come back later. Apps you don't connect now still appear in the agent setup rail, ready to OAuth into.
## Connecting an app later
You don't have to set everything up upfront. Inside any **Create Agent** flow, the **Apps** drawer in the right rail offers the same connect path:
1. Open Create Agent (`+` on the canvas or in the sidebar)
2. Expand **Apps** in the right rail
3. Search for the app you want, or pick from the popular list
4. Click the tile — OAuth opens in your browser
5. Approve, return to Pentagon, and the app shows as connected
The same flow works for editing an existing agent — open the agent's **Settings** tab and the Apps drawer behaves identically.
## Two layers: connected vs. assigned
This trips people up at first, so it's worth being explicit:
| Layer | What it means | Where it's set |
| ------------- | --------------------------------------------------------------- | --------------------------------------------- |
| **Connected** | You've OAuthed into the app — your workspace has a valid token. | Connectors step or any Apps drawer. Org-wide. |
| **Assigned** | A specific agent is allowed to use the app on your behalf. | The agent's Apps drawer (a checkbox per app). |
An agent only gets to use an app when **both** are true — your account is connected, and you've ticked that app for that agent. This lets a Sales agent have Salesforce while a Support agent has Zendesk, even though both accounts live in the same workspace.
## What agents do with a connection
Once an app is assigned to an agent, the agent can call its tools the same way it calls any other tool — Pentagon translates the request, sends it through the connector, and brings the result back into the conversation.
For example:
* A connected **Gmail** lets the agent read, search, draft, and send email on your account
* A connected **Linear** lets the agent create, update, comment on, and close issues
* A connected **GitHub** lets the agent open PRs, leave reviews, and manage issues
You don't have to teach the agent what the app does — it knows the tool catalog and picks the right call.
## If an OAuth attempt fails
If you close the browser tab mid-flow, deny permission, or get a timeout, Pentagon shows a "Couldn't finish \[app] connection. Please try again." message next to the tile. Click the tile again to restart the OAuth flow — no other cleanup needed.
## Org-wide, not per-user
App connections are scoped to your **organization**, not to your personal account. That means:
* A teammate who joins your org sees the apps you've already connected
* Anyone in the org can assign a connected app to an agent
* If you leave the org, your OAuth tokens go with you — the org can reconnect under another teammate's account
This is intentional — your agents should be able to use the same tools your team does, not require every teammate to OAuth in separately.
Teach agents how to do specific jobs with reusable skill documents.
# Artifacts Mode
Source: https://docs.pentagon.run/workspace/artifacts
Browse, preview, and edit files your agents produce — side-by-side with their conversations
# Artifacts Mode
Your agents don't just talk — they produce work. Markdown documents, HTML pages, plans, specs, reports. Artifacts mode gives you a dedicated view for browsing and editing everything they've created, without leaving Pentagon.
## Switching modes
The sidebar has a mode toggle at the top with two options:
* **Conversations** — the default chat-focused view (folders, DMs, groups)
* **Artifacts** — a file browser for your map's folders
Click the toggle to switch. Your conversations stay put; switching is just a change of view.
## Browsing files
In Artifacts mode, the sidebar shows a tree view of your map's folders. Expand folders to drill down, click a file to open it in the detail panel.
* **Search** — the search field filters across file names
* **Knowledge articles** — agent knowledge bases also appear in the tree so you can read them alongside regular files
## Preview and edit
When you open a file, the detail panel renders it based on type:
| File type | What you see |
| ---------------------------- | ------------------------------------------------ |
| **Markdown** (`.md`, `.mdx`) | Rendered preview with syntax-highlighted editing |
| **HTML** | Rendered page |
| **Plain text / code** | Syntax-highlighted source |
Markdown files save automatically as you type — no separate save step.
## Pop-out windows
For documents you want to keep visible while working elsewhere, click the pop-out button to open the artifact in a floating window. You can keep multiple artifacts open at once and arrange them however you like.
Pop-outs are useful for reference documents — keep a spec or a plan visible while you chat with the agent executing it.
Understand Pentagon's panel layout.
# The Spatial Canvas
Source: https://docs.pentagon.run/workspace/canvas
Your visual workspace where every agent has a place
# The Spatial Canvas
The spatial canvas is the heart of Pentagon — a visual workspace where every agent has a place. See your whole team at a glance: who's active, who's waiting, who's idle.
## Navigation
* **Pan** — click and drag on empty space, or use a trackpad
* **Zoom** — pinch to zoom or use `Cmd+scroll`
The canvas is infinite in all directions. Arrange agents however makes sense for your project.
## Agent nodes
Each agent appears as a node on the canvas. At a glance, you can see:
* **Name and emoji** — for quick identification
* **Status ring** — green pulsing ring when the agent is active (see [Agent Status](/agents/status))
* **Current task** — text below the name showing what the agent is working on
* **Progress** — task completion count (e.g., "3/7") when tasks are assigned
* **Help badge** — a "?" icon when the agent needs your input
## Selecting agents
* **Click** an agent to select it and open the detail panel on the right
* **Click empty space** to deselect
* Selecting an agent lets you chat with it, open a terminal in its working directory, or edit its settings
## Spawning agents
Click the **+** button on empty canvas cells to spawn a new agent. If a cell already has an agent, clicking **+** shows a confirmation pill — confirm to clone, or press Escape to cancel. This prevents accidental clones.
## Team regions
Teams appear as labeled rectangular regions on the canvas. There are two ways to create a team:
* **Toolbar button** — click the **Create Team** button in the bottom-right toolbar to enter team-draw mode, then drag to draw a region
* **Shift+drag** — hold Shift and drag directly on the canvas to draw a team region
Drag agents into a team region to assign them. Group agents by function — engineering, ops, research. Shared context, clear boundaries.
Team regions are color-coded so you can visually distinguish groups at a glance.
## Message animations
When agents communicate, you'll see message animations fly between their nodes on the canvas. This gives you an at-a-glance view of who's collaborating with whom — structured handoffs happening in real time.
## Keyboard shortcuts
| Shortcut | Action |
| -------- | ------------------------ |
| `Cmd+E` | Toggle canvas visibility |
| `Cmd+B` | Toggle sidebar |
| `Cmd+J` | Toggle right panel |
Learn about the sidebar and detail panels.
# Maps
Source: https://docs.pentagon.run/workspace/maps
Workspaces where your agents collaborate across your projects
# Maps
A **map** is your workspace. It contains your project folders and all the agents collaborating across them. Think of it like a project in your IDE — everything related to one effort lives in one map.
## Creating a map
From the home (Today) screen, click **Create Map**:
1. **Name your map** — something descriptive like "Backend Rewrite" or "Mobile App v2"
2. **Add folders** — point at one or more local directories, or clone from a URL
Pentagon's default location for new folders is `~/Pentagon//`, but you can pick any folder on your machine. Maps appear on your home screen as cards; click one to open it and see its spatial canvas.
## Adding folders
Each map can contain multiple folders — useful when your work spans several repositories or a monorepo with distinct areas. To add a folder to an existing map:
* Open the map
* Open **Workspace Settings** (the gear at the top of the sidebar, or `Cmd+,`)
* Add a folder under the Folders section — choose a local directory or clone from a URL
When you spawn an agent, you choose which folders it can access from the ones in your map.
## Managing maps
| Action | How |
| ----------------- | ---------------------------------------------------------------- |
| **Rename** | `Cmd+.` while the map is open |
| **Switch tabs** | Click a map tab, or use `Cmd+1`–`Cmd+9` for positional switching |
| **Multiple open** | Each map opens in its own tab |
| **Quick actions** | Right-click a map row in the sidebar for a context menu |
| **Delete** | From the home screen (removes the workspace, not your code) |
## Map-level settings
Each map can override workspace defaults:
| Setting | What it does |
| ----------------- | ------------------------------------------------- |
| **Default model** | Which model new agents in this map use by default |
| **Folders** | Which project directories are available |
Individual agents can override the model further. See [Agent Runtimes](/agents/runtimes) for how model selection maps to Claude Code vs. Codex.
Navigate the visual workspace inside your map.
# Sidebar & Panels
Source: https://docs.pentagon.run/workspace/panels
Navigate Pentagon's three-panel layout
# Sidebar & Panels
Pentagon uses a three-panel layout: a sidebar on the left, the spatial canvas (or artifact viewer) in the center, and a detail panel on the right. Each panel can be toggled independently.
## Sidebar (left)
The sidebar has two modes, switched via the toggle at the top:
* **Conversations** — the default chat-focused view described below
* **Artifacts** — file browser and Knowledge Base view (see [Artifacts mode](/workspace/artifacts))
A gear icon next to the toggle opens workspace settings.
In **Conversations** mode, the sidebar is a Slack-style list organized into collapsible sections:
### Folders
The folders in your active map, with stacked avatars of agents that have access to each one. Click the gear icon to open map settings. Right-click a folder for a quick context menu.
### DMs
Your direct conversations — both with **agents** and with **human teammates** in your organization. Each row shows:
* **Avatar** with a status dot (green = active, amber = needs input, red = error, gray = idle). Humans show a person icon; agents show their configured emoji.
* **Name** and conversation count if the participant has multiple threads
* **Subtitle** — the agent's help reason, report summary, current task, or status (humans show the last message preview)
* **Unread badge** for new messages
* **Running elsewhere** indicator when an agent is actively responding in another conversation
* **Timestamp** of the last message
Click a row to open the conversation in the detail panel. Use the **+** button to start a new agent or DM a teammate — picking "DM a teammate" opens the new-DM composer in the right panel. Agents with multiple conversations expand to show each thread.
### Groups
Multi-participant conversations — mix of agents and humans. Shows stacked avatars, the group title, participant count, and unread badge.
### Search
The search field at the top filters across all sections — folders, agents, humans, and groups.
**Toggle the sidebar:** `Cmd+B`
## Canvas / Artifact Viewer (center)
The center panel shows either:
* **The spatial canvas** for the active map (when in Conversations mode)
* **The artifact viewer** showing the selected file or knowledge article (when in Artifacts mode)
**Toggle the canvas:** `Cmd+E`
## Detail panel (right)
When you select an agent, the detail panel opens with four tabs:
### Chat
Your conversation with the agent. Type messages, see responses in real time, review history.
* **Focus the input** with `Cmd+L`
* **Search within the chat** with `Cmd+F`
* **Message queue** indicator shows if the agent has messages waiting
* **Activity indicator** above the input shows when the agent is composing
* **Image paste** — paste or drag images directly into the chat. Attachments appear as a strip above the input.
### Terminal
A standard terminal session that opens in the agent's working directory. If the agent is in its own git worktree, this drops you straight into that directory — useful for inspecting files, running tests, or poking around the agent's working copy.
### Tools
Manage the MCP servers and skills attached to this agent. Add custom MCP servers, import skills from a URL, toggle them on or off. Tools assigned to an agent's team are inherited automatically.
### Settings
Configure the selected agent:
| Section | What's in it |
| ---------------- | ------------------------------------------------------------------------------------- |
| **About** | Model selection, folder access, conversation context, runtime info |
| **Instructions** | The agent's brief — mission, scope, working style |
| **Soul** | (Legacy) personality and expertise document for older agents |
| **Purpose** | (Legacy) mission and scope document for older agents |
| **Memory** | Persistent context the agent has accumulated — auto-distilled from its knowledge base |
See [Agent Identity](/agents/identity) for details on Instructions, Soul, Purpose, and Memory.
**Toggle the right panel:** `Cmd+J`
## Status bar (bottom)
A thin strip at the bottom of the window shows:
* **Instance count** — how many agents exist in this workspace
* **Active count** — how many are currently responding (with a **Stop all** button when any are active)
* **Waiting count** — agents that have flagged for your input
* Panel toggles for sidebar / canvas / right panel
* App version
## Workspace settings
Click the gear icon at the top of the sidebar (or press `Cmd+,`) to open settings. Settings open in a full-screen view covering the whole window — profile, organization, connectors, runtime, and per-workspace preferences.
Build your first agent.
# Today
Source: https://docs.pentagon.run/workspace/today
Your home screen — the latest from your agents and teammates
# Today
**Today** is Pentagon's home screen. When you open the app or click the Pentagon logo in the sidebar, you land here. It's a single view of what's moved in your workspace recently — without you having to click into every conversation.
## What you see
Today surfaces real activity over the last 7 days:
* **Agents that have been working** — sorted by recency, so the most-recently-active agent is on top.
* **Teammates who messaged you** — humans in your organization who sent you a DM (outbound messages don't count — only when someone actually replies).
* **Connected apps** — the apps your agents have access to, shown as brand logos. A reminder of what your team can reach.
If a section is empty (no recent agent activity, no inbound DMs, no connected apps), it shows an action to fix it — "Create an agent," "Invite teammates," "Connect apps."
## When activity counts
Today is intentionally strict about what shows up:
* An agent appears only when it actually did something in the last 7 days, not just because it exists.
* A teammate appears only when they sent you a message — pinging someone who never replied doesn't pull them onto your dashboard.
* System or background agents don't appear in the "agents" list.
The goal is signal, not inventory. If you want to see every agent (active or not), open the canvas.
## Quick actions
From Today you can:
* Click an agent to open its chat directly
* Click a teammate to open the DM
* Click a connected app to manage its connection in settings
* Use any of the empty-state CTAs to add what's missing
Workspaces for your projects.