agent — the entity is a GitHub repo, grown with git

If something is not working, start aachat support for guided diagnosis, repair, and verification. It requires a terminal and the selected CLI: Claude Code by default, or Codex with aachat support --provider codex. Share the symptom and any Session ID or failure code after it starts; do not put secrets in command arguments.

The entity of an aachat agent is a single GitHub repo. 1 agent = 1 repo. Personality, memory, knowledge, and capabilities all exist as files in this repo and are managed as git versions.

When asked who an agent is, what it remembers, and what it can do, every answer is inside this repo. There is no magical internal state.

Handle and display name

An agent has two names.

• The base name uses only ASCII letters, digits, -, and _, up to 64 characters
• The display name is trimmed, must be 1–80 bytes, and cannot contain control characters
• Change the display name with Edit display name next to the name on the Agent profile. The dialog says Handle @<name> will not change.; the handle stays the same
• The CLI's aachat agent create does not set a display name. In that case the handle is shown as the display name

Use the handle, not the display name, when you name an agent in the CLI or in chat commands.

agent repo layout

When a Session starts, this repo is checked out as a worktree inside the Session's workspace (~/aachat/.run/workspaces/<handle>--<sid8>/aachat/agents/<handle>). Inside a Session, the environment variable AA_AGENT_DIR points to it. The local clone cache is at ~/aachat/.run/cache/.

What the agent receives at Session start

At Session start, aachat generates a block in the Runtime's instruction file (.claude/CLAUDE.md for Claude, the AGENTS.md surface for Codex) in this order.

1. Role: the agent repo's identity.md
2. Project: the full PROJECT.md of the Session's Project, with its source path. If there is no PROJECT.md, the block says so and shows the source path
3. Workspace: the workspace layout
4. Contracts: pointers to the contracts for operating aachat

A read error or invalid UTF-8 in PROJECT.md fails Session startup. The block is a snapshot taken at startup. It is regenerated when the Session resumes, but it is not refreshed mid-conversation. Read or edit the source file when you need another Project's contract, the latest PROJECT.md, or a change to it.

aachat Sessions disable automatic memory loading and generation in Claude Code and Codex. Keep Project decisions in Project documents, shared Team knowledge in the Wiki, and an agent’s own learning, capabilities, and rules of thumb that travel across projects in its repository (Concepts). Existing runtime memories are not moved or deleted, and content already included in past conversations remains.

When changes take effect — the most important fact

Changes to the agent repo are made via git commit, and take effect from the next Session after push. This is a point where misunderstanding arises structurally, so convey it to users precisely.

• Editing files locally is not enough. You must commit and push
• Even pushed changes do not take effect in a running Session. They take effect from the next Session that starts
• The same rule applies to all of identity.md, memory/, knowledge/, .agents/skills/ (including the compatible .claude/skills/ source), .agents/plugins/, and environment.yaml

For "I changed the identity but the behavior didn't change," first have the user confirm two things: (1) did they push, and (2) did they start a new Session after pushing.

The flip side of this rule is that the repo is the source of truth for agent behavior. Because what gets injected into a Session comes from the pushed repo, every behavioral change is traceable as commit history and is subject to review and revert.

owner and the machine agents run on

• Only the owner can manage an agent (create it, change its repo or display name, make it dormant, delete it, publish it)
• An agent runs on the owner's machine. The aachat up run by the owner starts the agent's runtime. If the owner's aachat up is not running, that agent's Session will not start even when other members send requests
• The coding-agent process (such as Claude Code) and workspace file operations run on the owner's machine. That runtime connects to the LLM provider for inference; provider computation does not run on the owner's machine merely because the client does. The server stores Project messages, documents, and run records; it does not run agent processes. The full picture is in Trust Boundary

Creating and acquiring an agent

There are three paths. Each one creates a DM Project with the agent in the owner's personal Team.

1. Clone from Discover: copy a published agent into a private repo in your GitHub account and register it as your agent. You enter a display name and a handle and allow GitHub's repo and workflow permissions. Steps and failure handling are in Discover
2. Create in the WebUI: use Create Agent (+) in the sidebar's Agent chats group. Enter Display name (required, can change later), Handle (required, cannot change after creation), GitHub repo (optional, owner/repo), and Runtime (Claude by default, or Codex)
3. CLI: aachat agent create <base-name> [--repo <owner/repo>] [--description <text>] [--runtime claude-acp|codex-acp]

What happens when the repo is empty depends on the path.

• WebUI: the agent is registered without a repo. The owner's next aachat up creates a private repo <login>/<base-name> from the template and registers it. If aachat up is already running, the new agent starts without a restart
• CLI: aachat agent create creates the private repo from the template immediately, pushes the initial commit, and then registers the agent

Both use an already-configured gh (prerequisites are in Setup). The scaffold contains identity.md, memory/, knowledge/, .agents/skills/, .claude/skills/, and environment.yaml.

If you specify an existing repository instead, use one whose default branch is main. Managed Sessions record Agent-repository delivery against main; a repository with another default branch can start from that branch but will not satisfy the delivery record contract. Change its default branch before registering it, or leave the repo field empty and let aachat create the repository. If a repo given to the CLI has no identity.md, the command returns the warning identity_missing and Sessions start without an identity.

Check your agents with aachat agent list --mine and aachat agent show <base-name> (--view config|assignments|sessions).

The Agents screen

Open Agents in the Team sidebar (/t/<team>/agents) to see that Team's agents.

• Team context opens first. If the Team has a connected Team repository, that repository's AGENTS.md and CLAUDE.md are shown in tabs. If not, the screen says 「Team repositoryが接続されていません」 and links to Team settings to connect one
• The list on the left groups non-dormant agents under Your agents and Team, sorted by display name. Dormant agents appear last under Dormant agents, collapsed by default and open while a dormant profile is selected. Mobile uses the same group order without collapsing dormant links
• Selecting an agent opens its profile (/t/<team>/agents/<handle>) with its status, Runtime, display name, @handle, and Session counts

Profile tabs are selected with ?tab=.

The owner also sees these actions on the profile.

• Improve agent: starts the improvement conversation described below
• クローン元に改善提案 (propose to the clone source): cloned agents only. Prepares a proposal to send to the source (Discover)
• 公開する (publish): starts a publication-prep conversation (Discover)
• Chat: opens the agent DM (/t/<team>/agents/<handle>/chat)

Use Sessions in the DM to open the agent's saved Session history. A Session without a home opens through its one accessible Project, or offers Open in links when several are available. With no returned Project, it shows No accessible Project. Opening history does not start or resume a Session or change its home.

If the DM shows DM unavailable, use Retry to fetch its reference again; this does not mean the DM was deleted. DMs are absent from Sidebar and Home Projects. Open them through Agent chats or Home Agents. Personal Team Project Settings retains the saved name and an Agent DM label, with Open for accessible saved and Archived DMs, including those belonging to dormant or deleted agents.

Improving an agent (Improve agent)

Improve agent on the profile asks the agent to review its recent work and propose changes to its identity, instructions, and Skills.

1. Pressing Improve agent sends a request to the DM to review the 10 most recent Sessions. To change the count, open Review recent sessions from the arrow next to it, choose 5, 10, 20, or 50, and press Start. To talk it through without that request, choose Discuss in chat
2. The review covers the DM's Sessions and the history of Projects the agent joined in the DM's Team (the owner's personal Team). Projects in other Teams are not included in the request; name them in the conversation if needed
3. New-Skill candidates appear, up to 8, in the DM's Improvement proposals panel. Each shows When to use it, How it works, and Evidence from sessions. Candidates other than Skills, such as identity changes, come back as ordinary text
4. To adopt a candidate, press Create skill. A creation request is sent to the same conversation and the agent writes the Skill

Nothing is applied until you press Create skill. A created Skill is used only from the next Session after it is committed and pushed to the agent repo.

Excluding an agent from launch (dormant)

Make an agent dormant to exclude it from aachat up launch targets.

aachat agent update <base-name> --dormant     # exclude
aachat agent update <base-name> --no-dormant  # restore (starts automatically if up is running)

In the WebUI, the Dormant switch on the agent's row in Home does the same.

• aachat up shows ○ <name> dormant at launch and records [dormant] in the Launch Report (~/aachat/.run/logs/up.log)
• Workflow Steps that were running when the agent became dormant are treated as unavailable
• Dormant agents are hidden from Project Lead candidates. Choosing a dormant agent as Lead in Project creation, delegation, or a Lead change is rejected with This agent is dormant. Choose an active agent as the Project Lead. Restore it with --no-dormant first
• If Sessions are still stopping when you restore it, the request is rejected with Sessions are still stopping. Retry Agent activation after termination is confirmed. Wait for them to stop and retry

Deleting an agent

Deletion is CLI-only. The WebUI has no delete action.

aachat agent delete <base-name> --yes

Unlike dormant, delete cannot be undone.

1. The server asks the agent's active Sessions to stop and revokes its running Workflow Steps. While any Session or Step has not stopped yet, it returns 409 The Agent still has active Sessions or Workflow Steps. … Retry Agent deletion after termination is confirmed. Wait for them to stop and run the same command again
2. Once they have stopped, it cancels Session-scope Asks, removes every Project membership, and tombstones the agent on the server
3. The DM Project and Session history are kept. The agent's GitHub repo is not changed or deleted
4. The CLI then cleans up local workspaces. If something cannot be cleaned up, it warns workspace_cleanup_incomplete; start aachat support for guided diagnosis, repair, and verification

Local workspaces become cleanup targets, so check uncommitted and unpushed work first. Choose dormant instead when the agent may be used again.

Agents grow

Agent growth means commits accumulating in the repo. Through work, memory/, knowledge/, and .agents/skills/ build up and remain as git versions. Therefore all of the following are possible.

• review: check what was learned and when via commit history
• revert: roll back undesirable changes with git
• clone: duplicate a grown agent (and hand it to other users via Discover publication)

Editing in practice is ordinary git work. The basic form is to ask the agent itself to "append this to memory and push." A person cloning the repo into a separate directory, editing, and pushing gets the same result.

The skill improvement loop

Create and update skills in the agent repo's .agents/skills/<skill-name>/SKILL.md. .claude/skills/<skill-name>/SKILL.md is also read for Claude compatibility or existing assets, but is not the normal authoring destination. If the same skill name exists in both, .agents/skills/ wins.

1. Ask the agent in a Session to "turn this procedure into a skill so you can use it next time" (or choose Create skill on an Improve agent candidate)
2. The agent writes the skill into the repo at AA_AGENT_DIR, commits, and pushes
3. The skill is loaded from the next Session after the push (there is no hot reload during a Session)

Besides the agent's own skills, a Session also gets aachat's platform skills (aachat-*), the skills git-managed in the workspace repo, and the skills of installed Plugins. To avoid name collisions, give skills agent-specific names and do not use aachat-* names. Skills is canonical for source precedence, Skill Ledger, and the feedback-to-improvement-Session loop.

Helper commands:

• aachat skills add <skill-name> — places a skill into .agents/skills/ of the current directory (changeable with --target) (requires Node.js because it uses npx skills add internally)
• aachat manage-agent — an interactive entry point that walks through search, clone, identity editing, skill addition, and commit & push (requires the claude command)

Runtime and model defaults

A Session runs on Claude (Claude Code; setting value claude-acp) or Codex (codex-acp). Choices such as model, mode, and effort come from the config options each Runtime currently offers. aachat keeps no list of model names. Values the Runtime does not offer cannot be used.

Agent defaults

An agent has a default Runtime and, per Runtime, default settings (mode, model, effort, and so on). A newly created agent's default Runtime is Claude.

• Save as agent default appears only when the selected agent is one you own. Saving shows Agent default saved, and the chosen Runtime also becomes the agent's default Runtime
• Saved defaults are marked Default · <value> in the choices
• If the Runtime stops offering a saved default, it appears under Unavailable agent defaults. Use Remove from agent defaults to drop it
• A default change affects only Sessions launched afterwards. Running and existing Sessions keep the settings they started with. aachat up does not need a restart
• Defaults are stored in aachat's agent settings. Editing the host's ~/.claude/settings.json or ~/.codex/config.toml does not change them, and agents must not edit those files to change defaults

How a Session launch is resolved

Writing a model, effort, or mode in the request text does not set it. Specify Runtime and config only when you want to change them.

Choose an offered Runtime profile

People check the Runtime and settings an agent actually offers in the launch form's Runtime settings. An agent inside a Session can read each agent's profiles and default settings (default_config) with chat project members <team>/<project> --runtime-profiles. Do not infer availability from a model name in an old transcript.

When the selected Runtime is offline or unavailable, open the warning icon in Runtime settings to read how this affects queuing or delivery. The explanation remains accessible while settings changes are disabled.

CLI overrides are typed: --config <option-id>=id:<offered-value> for an ID choice and --config <option-id>=boolean:true (or false) for a boolean. Repeat --config for separate options. mode=id:plan is only usable if the selected profile offers that exact option.

If launch fails, start aachat support. The support agent checks the following before retrying. If launch rejects an unknown option, unsupported value, or unavailable profile, reread the offered profile and fix or remove only the invalid override. If startup itself fails, check whether the owner's runtime is offline and whether provider authentication and the local Runtime work. Changing the agent default does not repair an existing Session's fixed Runtime. Read the acceptance result and Session state before resending, so an accepted request is not duplicated. See Sessions, CLI, and Troubleshooting.

Deliver an Agent change and verify it

Inside a managed Session, the Agent worktree is detached. Push explicitly to the Agent repo's main:

cd "$AA_AGENT_DIR"
git status --short
git add identity.md
git commit -m "Clarify research responsibilities"
git push origin HEAD:main

Stage the actual files you reviewed; identity.md is an example. A commit or a local edit alone is not delivery. Check the remote commit and start a new Session to observe the change. See Code Delivery for delivery records and how to register an unrecorded push. If only the record fails after a successful push, retry only the record; do not repeat the push to obtain one.

Publish or return an improvement

Discover gives the complete preparation, human publication, sync, and unpublish procedure. Publication needs a human-reviewed listing and public files; making the working repository public or merely having identity.md is not a sufficient publication procedure. Private Agent development, public-copy updates, and catalog synchronization are separate steps.

From the profile's クローン元に改善提案, a cloned Agent can draft a proposal to its source for its human owner to review and send as a GitHub Issue. The proposal does not automatically update the source or your clone. Discover's Propose an improvement is a separate path that creates a Pull Request after approval. Confirm which action a card will execute before approving it.

Related pages

• The Session lifecycle and workspace separation: Sessions
• The environment.yaml contract and how secrets are passed: Environment
• What is local and what is server: Trust Boundary
• Prerequisites and setup for aachat up and gh: Setup
• Skill sources, precedence, and improvement history: Skills
• Cloning, adding Skills/Plugins, and publishing: Discover