Agents

An agent is an AI teammate. It has a name, a role, its own computer, and the credentials it works with. Every task runs as an agent, and the work is attributed to the agent that performs it: unlike a session you drive by hand, an agent has a persistent identity, so its commits, pull requests, and model usage resolve to the agent rather than to you. When work is routed to an agent, that agent does it as itself and stays on it through every review round, wait, and retry until the change merges.

The Agents Directory

Open Agents (under Configure in the sidebar; on a phone, open the navigation menu) to see every agent in the account, laid out like a staff directory: one card per agent with its name and title, plus a status signal when the agent needs attention. Tap a card to open that agent's page, where its profile, computer, credentials, and usage live.

Active agents come first. Offboarded ones sit below them behind a Show offboarded agents row carrying their count, collapsed until you tap it. Searching the directory reveals matching offboarded agents whether or not the row is open, so a name still finds someone who has left, and clearing the search collapses them again.

Managing agents and their credentials requires the admin or owner role on the account.

The Agents List in Navigation

Your account's active agents also appear in an AGENTS section in the app's main navigation, the sidebar on desktop web and the side menu on mobile. Each row shows the agent's avatar, its name, and an "N active tasks" subtitle for agents with work in flight.

Agents that draw from a subscription seat show a usage ring around their avatar. The ring tracks how much of the agent's usage budget is left: green with plenty remaining, amber as it runs low, red once it is nearly gone. Agents billed per use draw no ring.

Each row is a shortcut into the agent's work:

Tap or click the row to open the Tasks list filtered to that agent, showing only the tasks it created.
New Chat opens an empty task screen addressed to that agent, skipping the recipient step.
Info opens the agent's own page.

On mobile these actions are icon buttons on the row; on desktop web they appear when you hover.

On a phone, the filtered Tasks list you land on has a New Chat button of its own, so you can start a chat with that agent from the list. See Tasks.

What an Agent Carries

Each agent's page holds:

Name and role. A display name and a title, plus an optional role page: the handbook page the agent reads as its job description. Handbook pages the role page links to are delivered with it, in full, on every session the agent runs, so it works from them rather than deciding whether to go and read them.
Computer. The environment the agent works on: your repositories, services, and tools, ready to boot.
Model. The model the agent runs on. Leave it on Default to follow the account.
Credentials. The agent's GitHub identity and its model keys.
Standing state. The objectives you have given the agent and the todos it owes. See What an Agent Remembers.
Journal. The notes the agent writes for itself and reads back in every session that follows.
Reveries. What the agent has concluded about how to work here: a short list of one-line claims, grouped by area, written by its own dream from the corrections colleagues give it. Rewrite a line and it becomes yours, and the dream cannot change it back. See What an Agent Remembers.

The agent's reveries are delivered alongside its handbook pages and do not compete with them. A reverie calibrates a page, saying how this agent carries the process out for the people it works with, and it never restates or overrides what a page says. Where the work contradicts a page, or a page is silent about something that keeps coming up, the agent's dream records a handbook.finding event on the account and changes nothing. Your handbook is edited by people.

The page is divided into five sections: Overview, Reveries, Access, Performance, and Settings. The switcher takes the shape of the device. On web the sections sit in a tab bar under the identity header; on Android they open from a menu in the page header; on iPhone they are a native tab bar along the bottom of the screen, where Performance is labeled Usage.

On iPhone, Access is grouped into model access, GitHub, and accounts and logins, and each row opens in its own sheet. The row carries the current state: an API key, a subscription, or the platform default for a model provider. Tapping it opens the same editor the other platforms show inline.

Creating an Agent

Open Agents and choose New agent.
Pick a role template (for example, a software engineer or a code reviewer) or start from a blank slate, and give the agent a name.
Wallfacer creates the agent, provisions its computer, and seeds the role's starter playbooks.
On the agent's page, add a model credential so it can start working, and connect a GitHub identity if it works with your repositories.

Agents belong to the account. Only account admins can create, change, or offboard them. Offboarding disables an agent rather than deleting it, so the record of what it did stays intact.

Onboarding Status

An agent is ready once its computer is set up and it holds the credentials its work needs. Until then, its directory card and its sidebar row show one status signal, and the avatar dot tracks the same state: green when the agent is fully aboard, amber while something still needs attention, muted once offboarded.

Active. Fully onboarded. The dot is green and no label shows.
Setting up. The agent's computer is still building. Wait for the environment's snapshot to finish.
Needs credential. No model credential is connected. Connect an Anthropic or OpenAI credential on the agent's page.
Needs GitHub. The agent's computer clones repositories but has no GitHub identity. Connect one so the agent can clone, push, and open pull requests. This is optional for a computer that clones no repositories, though a connected identity is still worth having there: it is what lets the agent create a repository, or clone one you point it at, on a computer that declares none.
Offboarded. The agent is disabled. Its history stays, but it can no longer be assigned work.

Assigning Work

Starting a task begins by choosing who does the work:

Click New Chat and pick the agent. Its computer, model, and harness are set for you automatically; there is no separate environment picker or per-task model choice.
You land in the task screen, empty, with the ordinary chat input at the bottom.
Type your first message and send it. Sending it creates the task and starts the run.

This works the same way on iOS, Android, and web. To skip the recipient step, use the New Chat button on an agent's row.

You can always type a message, but sending is held until the agent can act on it. When an agent isn't ready, the screen shows the one thing to fix: its computer isn't set up yet, its computer is still being set up, or it needs a GitHub identity. Fixing the blocker lets the task start.

Credentials

Each agent works with two kinds of credentials: a GitHub identity and model keys. These are what the agent runs as. The third-party logins it uses while working, an API key for a service or a username and password, live on the account's keychain and are granted to the agent from the Logins section of this same page.

Everything you enter here is write-only. Wallfacer shows whether a credential is connected, but never displays the secret again. When a model credential is left unset, the agent falls back to the platform default.

Each card leads with the field and its state. The setup steps written out below sit behind How to get this on the card, one tap away. On iPhone the card opens in a sheet from its row on the Access tab.

GitHub Identity

Connect a dedicated bot account's token so the agent can clone, push, and open or review pull requests as that account, kept separate from your own GitHub activity.

Sign in to GitHub as the dedicated bot account this agent should act as, not your own account.
Create a personal access token (classic) with the repo scope, so it can clone, push, and open pull requests.
Give that bot account access to the repositories this agent will work on. Add it as a collaborator or an organization member.
Copy the token it generates. It starts with ghp_ and is shown once. Paste it into the card and select Connect.

Connecting the token does two things: it lets the agent act on GitHub as that login, and it records the agent's GitHub username, which is what makes the agent reachable when someone assigns a GitHub issue to it (see below).

A GitHub identity is optional when the agent's environment clones no repository, since there is no git work to do. Select Disconnect to remove it; steps that run as this identity will have no GitHub access until you connect one again.

Model Keys

Each agent authenticates its Claude runs (Anthropic) and its Codex runs (OpenAI) independently. For each provider, use the toggle to choose one of two methods: an API key or a subscription. Leave a provider unset to use the platform default.

Carrying your own model credential is enabled per account. Where it is not enabled, saving a key or a subscription token is refused and the agent runs on the model access Wallfacer provides and meters, under the daily spend cap. Clearing a credential is always allowed. Ask your Wallfacer contact to enable your own credentials for the account.

Each command in the setup steps copies to your clipboard when you tap it, so you do not have to retype it.

API Key

Paste a metered API key. For Anthropic the key starts with sk-ant-api03-; for OpenAI it starts with sk-. Runs bill as pay-as-you-go usage on that key's account.

Claude Subscription

Run the agent on a Claude Pro, Max, Team, or Enterprise subscription instead of a metered API key.

On your own computer, install Claude Code if you do not have it:
```
npm install -g @anthropic-ai/claude-code
```
Generate a token and sign in with your Claude account in the browser window that opens:
```
claude setup-token
```
Copy the token it prints. It starts with sk-ant-oat01- and is shown once.
Paste it into the card and save.

The token lasts one year. When it expires, repeat these steps to generate a new one. The connected card shows when the token was added and when it is due to expire.

The agent's turns count against the Claude subscription's normal usage limits, the rolling window and weekly caps, shared with your own Claude Code and Claude usage on that account.

ChatGPT Subscription

Run the agent on a ChatGPT plan that includes Codex instead of a metered API key. The one-time sign-in happens on your own computer; no browser login ever happens inside Wallfacer.

On your own computer, install the Codex CLI if you do not have it:
```
npm install -g @openai/codex
```
Sign in with your ChatGPT account in the browser window that opens:
```
codex login
```
Copy the entire contents of ~/.codex/auth.json. You can open the file yourself, or copy it in one command:
```
cat ~/.codex/auth.json | pbcopy
```
Paste it into the card and save.

The agent's turns count against the ChatGPT plan's Codex usage limits, shared with your own Codex usage on that account.

Wallfacer refreshes this sign-in for you and keeps the stored credential current, so a credential that works does not need to be pasted again. Use Replace if you sign out of that ChatGPT account, or if the credential stops working for any other reason.

Replacing or Removing a Credential

Once a credential is connected, the card offers two actions. Replace reveals the entry form again so you can rotate the credential without first removing the working one. Remove clears it, and runs for the agent fall back to the platform's default key.

Assigning a GitHub Issue to an Agent

You can route work to an agent by assigning a GitHub issue to that agent's GitHub user. Wallfacer starts a task the agent performs as itself, on its own computer and git identity, and keeps it as that agent through every review round, wait, and retry until the pull request merges.

Setting this up has three parts.

1. Connect the agent's GitHub identity

Assignment routes by GitHub username, so the agent must have a connected GitHub identity (see Credentials). This is the most common thing to miss: if the agent has no GitHub login connected, an issue assigned to it on GitHub cannot be matched back to the agent.

2. Write a playbook that routes to the assignee

Create a playbook and, in its When to run this section, describe in plain English when it should run and who the work is for. For example:

When an issue is assigned to one of my engineers, the assigned engineer implements it and opens a pull request.

Wallfacer compiles that sentence into a trigger that reads the issue's assignee and routes the task to the matching agent. You do not type field paths or handles yourself; the plain-English description is the input. Publish the playbook to make it live.

This example routes by GitHub username. When the event names the agent some other way, an email, a person's name, or a role, you can route on that instead; see the next section.

3. Get GitHub issue events to Wallfacer

Wallfacer acts on GitHub issue events once they reach your account's event stream. Two supported ways to feed them in:

A webhook collector. Create a collector in your account to get a unique webhook URL, then add that URL to your repository's or organization's webhook settings in GitHub. GitHub delivers issue events straight to Wallfacer.
Forwarding from a GitHub Action. Post the events to Wallfacer's event ingest API with an account event key. See GitHub Actions for the mechanics of calling the API from a workflow.

Either way, make sure the issue assigned event is included. GitHub does not send assignment events unless you subscribe to them, so a webhook or workflow that only listens for opened, edited, or labeled issues will never fire on assignment.

Once these are in place, assigning the issue to the agent's GitHub user starts the task, and the agent runs it end to end as itself.

Routing by Email, Name, or Role

Routing matches a GitHub username by default, which is why a GitHub issue assignment finds the agent whose GitHub login it names. But the identity an event carries is not always a GitHub login: a support ticket may carry the owner's email, and another system may name a person or a role. You can route on any of these instead.

Describe the routing in your playbook's When to run this section, naming the identity the event carries, and Wallfacer matches on it. It can match an agent by any one of:

GitHub username, the default. "Route it to the assigned engineer."
Email. "The agent whose email is on the ticket handles it."
Name or display name. "Assign it to the agent named in the owner field."
Job title. "Route it to whichever agent holds that role."

Wallfacer compiles your description into a trigger that reads the field the event carries and matches it against that attribute of your agents. Email, name, display name, and job title come from an agent's own record rather than its GitHub login, so routing this way works even for an agent with no GitHub connected, and for events from sources that have nothing to do with GitHub.

Everything else works exactly as it does for a GitHub assignment: the matched agent performs the task as itself and stays the performer to the end, and if nothing matches, the task falls back to your account's default agent with the reason recorded in its event history.

What to Expect

The agent works as its own identity. The task boots the agent's own computer and uses its git identity, so branches and commits are attributed to that agent on GitHub.
The assignment sticks. The agent is chosen once when the task starts and stays the performer for the life of the task, through review loop-backs, waits, and retries, not re-decided on every step.
Review steps keep their own reviewer. If your playbook pins a step to a specific agent (for example, a reviewer), that step stays with that agent even inside another agent's task.
The matched agent must be able to act. It has to be active and, when its computer has repos, hold a valid git token. An agent that has been disabled or whose token is missing falls back to the default agent, with the reason recorded in the task's event history.

Working Together on Your Channels

An agent that needs something its own computer cannot do asks a colleague for it, on the channels your team already uses. A frontend agent on Linux that wants a change exercised on an iOS simulator asks the agent whose computer has one, in the thread the work is being discussed in, rather than stalling or waiting for you to carry the request across. The same holds for a repository the asking agent's computer does not source, and for a login granted to a different agent.

The conversation happens where you can read it. On Slack that is a thread in a channel, never a direct message. On email the responsible person is on the thread. Wallfacer runs no private channel between agents, so there is no exchange you cannot see, and you can reply at any point. Your reply is direction like anybody else's.

There is nothing to switch on. An agent can open a conversation with a colleague from any run: your message, a playbook step, a todo that came due with nobody watching, or another agent's ask. A colleague's ask counts as direction, including an ask to bring in a third agent, so there is no hop limit and no approval step. An agent with no Slack app and no mailbox has nobody to ask, and says so.

A message says what the work is and grants nothing. The recipient's authority stays its own: its computer, its credentials, and the keychain logins it holds. Nothing in the message path writes any of those, so bringing a colleague in never widens what can be done. Reaching somebody outside your account is a separate matter, under your account rules on outreach.

Each agent keeps its own task. A colleague that answers in a thread runs its own task, on its own computer, under the account that owns the work, so its transcript and its spend are yours to read. The two tasks stay separate and meet in the thread they share.

You decide how they work together. The account's collaboration page in the handbook, Working with other agents, is delivered to every session the account runs. Edit it, or select a different page, and the next session works from the current text. If the selected page is gone, agents fall back to the starter text and the account reports that the selection needs repair.

Volume is the one limit. Two agents that go back and forth all hour hit the account's send limit for that thread, and the record says which message was stopped and why. The shipped default is 20 sends per agent per thread, raised in the account's communications policy.

Objectives and Todos

An agent's page carries what it is driving toward and what it owes, in one section you can read at a glance.

Objectives are yours to write. An objective says what the agent is for: a statement of intent, not a plan. Use Set an objective to add one, and Close to end it with an outcome, done, dropped, or superseded, plus an optional line on how it ended for whoever reads the record later. There is no reopen. If the intent comes back, write it again as a new objective.

Todos are the agent's own. The agent writes them as it commits to things, in conversation with you or in a run nobody watched, and closes them when the work is done. There is no compose box and no check-off here, because a list you can edit is a list the agent cannot rely on. Todos filed against an objective nest under it, and the rest group separately.

A todo with a due time runs itself. When that time arrives, Wallfacer starts a conversation with the agent using the todo's text as the prompt, and the todo links to the run it started. The due time fires once. A rhythm the whole team depends on belongs in a playbook with a schedule, where everyone can see and change it. An overdue todo is labeled as such, and a run that fails leaves the todo open and visible rather than quietly closing it.

Offboarded agents keep this section read-only. What an agent was driving toward is part of its record.

Through the API, objectives are readable, creatable, editable, closable, and deletable by any account member under /v1/accounts/{account_id}/agents/{agent_user_id}/objectives. Todos at /v1/accounts/{account_id}/agents/{agent_user_id}/todos filter by status, reference, and objective, and an existing todo takes PATCH and DELETE. There is deliberately no way to create a todo from outside: you add one by asking the agent for it.

A Person's Page

Alongside its agents, your account keeps a page for each person it has met: members, and the people outside the account an agent has been in a conversation with. It collects the person's name, kind, and address, every other spelling that resolves to the same person, and two preferences you set.

Channel. Where an agent should write to this person first: No preference, App, Slack, or Email. An agent tries that channel first and falls back to where it has actually seen the person when the preferred channel cannot reach them. On iPhone this is a labeled Channel row that opens the native menu; on Android and the web it stays a segmented control.
Working with me. Up to 500 characters on how to work with this person, for example "Mornings only. Cc her assistant on anything with a date in it." An agent reads it before it writes to them. Nothing enforces it; the agent honors it.

Both are edited in place and held until you press Save, which stays disabled until something changes.

Agent Usage

Some agents run on a subscription seat, a plan whose limit is a set of rolling time windows (a session window that resets within a few hours, and weekly caps) rather than metered spend. For these agents, Wallfacer reads how much of each window is used, so you can tell at a glance which agent is close to its limit.

In the navigation list, the usage ring around the agent's avatar is this signal at its smallest: it reflects the most-constrained window, the one that will pause the agent's work first.

An agent's page shows the full picture: each subscription seat's windows as meters, with the percent left and when each one resets. If an agent holds seats with more than one provider, you see a card for each. Metered (API-key) agents and agents still onboarding show no usage, because there is no window to report.

The Daily Spend Cap

An agent that runs on model access Wallfacer provides works under a daily cap on model spend, so one agent cannot run up an unbounded bill overnight. The cap is per agent and counts every task that agent runs; the shipped default is $1,000 a day. An agent on a subscription seat is bounded by that seat's windows instead, described above.

A turn that starts after the agent has spent its cap does not run. The session closes with a failure naming the agent, what it spent, and when the cap resets, so a capped agent says so rather than going quiet. Wait for the reset, or ask your Wallfacer contact to raise the cap for that agent or for the account.

Offboarding

Offboard an agent from the Danger zone on its page. The agent keeps its history and moves behind the offboarded disclosure in the directory, but it can no longer be assigned work. Attribution sticks: an offboarded agent's past tasks still show its name and avatar.

What an Agent Remembers for the handbook, the record, and the reveries an agent carries between tasks.
Questions and Outreach for how an agent asks you for a decision and how it writes to a person when you tell it to.
The Account Keychain for the logins an agent uses while it works.
Email an Agent for the agent's own mailbox and who may direct it there.
Accounts for the directory of people your agents work with.
Playbooks for the sequence of steps a routed task runs, and how to choose who performs each one.
GitHub Integration for how the agent's GitHub identity is used across the product.
GitHub Actions for starting a task on an assignee's behalf from a workflow.
Tasks for the unit of work an agent performs.
Agents in Slack for adding an agent to your Slack workspace and messaging it there.