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

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. Agent names use the {base}.{owner} format (example: researcher.kensaku) — the owner's GitHub login is appended to the base name to form the full name.

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.

agent repo layout

When a session starts, this repo is checked out as a worktree inside the session's workspace (~/aachat/.run/workspaces/<full-name>--<sid8>/aachat/agents/<full-name>). The local clone cache is at ~/aachat/.run/cache/.

The agent repo is canonical for the agent's own learning, not for the deliverables of an individual project. The next session combines identity / memory / knowledge / skills from the agent repo with project-side context. When a task needs that context, it reads PROJECT.md first as the stable Project Contract / Context Router, then follows the curated Context Map to the Shared Documents it needs. It reads dynamic handoffs from a session transcript, short project message, or normal Shared Document. Keep settled deliverables and project-specific decisions on the project side; keep capabilities and rules of thumb that travel across projects in the agent repo (Concepts).

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 for changes to take effect. You must commit and push
• Even pushed changes do not take effect in a running session. They become effective 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), and environment.yaml

For the question "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, local-only configuration drift never changes agent behavior. Every behavioral change is traceable as commit history and is subject to review and revert. When a team wants to govern agent behavior, this history serves directly as the audit record of changes.

owner and the machine agents run on

• Only the owner can manage an agent (creation, repo changes, making it dormant). Team members other than the owner cannot manage the agent
• 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, Shared Documents, and session records; it does not run agent processes. The full picture of this boundary is in Trust Boundary

Creating and acquiring an agent

There are three acquisition paths.

1. Clone from Discover: duplicate a published agent as your own agent. Cloning also automatically creates a DM project with that agent (dm:<full-name>)
2. Create in the WebUI: from Create Agent in the "Agents" sidebar. Names use alphanumerics, hyphens, and underscores. The GitHub repo field is optional (leaving it empty is the easy path). The runtime is Claude (default) or Codex
3. CLI: aachat agent create

When an agent is created without specifying a repo, the first aachat up automatically creates a private repo <login>/<agent-name> from the template and lays out the scaffold (identity.md, memory/, knowledge/, the normal .agents/skills/ source, and the compatible .claude/skills/ source) (this uses an already-configured gh; prerequisites are in Setup). If aachat up is already running, the new agent is started automatically without a restart.

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 receipt contract. Change its default branch before registering it, or leave the repo field empty and let aachat create the repository.

Excluding an agent from launch (dormant)

Agents you will not use for the time being can be excluded from aachat up launch targets with the dormant flag.

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

Dormant agents are shown as ○ <name> dormant at launch and recorded as [dormant] in the Launch Report (~/aachat/.run/logs/up.log).

Deleting an agent

aachat agent delete <agent-name> --yes

Delete is irreversible and is not the same as dormant. It cancels active sessions and Session-scope Asks, deletes the owner's DM, removes every project membership, and tombstones the server agent. Local workspaces also become cleanup targets, so inspect uncommitted / unpushed work and any needed DM or session record 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 the normal .agents/skills/ source 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 operations. The easy way is to directly edit the worktree checked out inside a running session's workspace.

# <sid8> is the first 8 characters of a session ID, found with aachat session list --agent <base-name>
cd ~/aachat/.run/workspaces/<full-name>--<sid8>/aachat/agents/<full-name>
# edit files
git add <reviewed-files>
git commit -m "<change description>"
git push origin HEAD:main

Cloning normally into a separate directory, editing, and pushing yields the same result. You can also have the agent grow itself by asking it to "append this to memory and push."

The skill improvement loop

Create and update skills in the agent repo's normal source, .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, the .agents/skills/ source takes precedence. The basic form of the improvement loop is to route it through the agent itself as a self-improvement request.

1. Ask the agent in a session to "turn this procedure into a skill so you can use it next time"
2. The agent writes the skill into its own repo (which the environment variable AA_AGENT_DIR points to inside a session), 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-*) and the skills git-managed in the workspace repo projected into it. 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 the normal .agents/skills/ source of the current directory (changeable with --target) (requires Node.js because it uses npx skills add --agent universal internally)
• aachat manage-agent — an interactive entry point that walks through search, clone, identity editing, skill addition, and commit & push in one flow (requires the claude command)

Default Runtime and per-Session selection — Claude Code / Codex

Each new Session runs on either Claude (Claude Code; claude-acp) or Codex (codex-acp). An agent's setting is only the initial default for future launch drafts; the selected Runtime is fixed independently for each Session. The default is Claude.

• Changing the default affects only future launch drafts. It does not change running or existing Sessions and does not require restarting aachat up
• Choose a Runtime per Session in the WebUI composer or with session run --runtime claude-acp|codex-acp
• The selected Session Runtime determines workspace projections: Claude uses .claude/ (CLAUDE.md and .claude/skills/), while Codex uses AGENTS.md and .agents/skills/. The agent repo's skills are loaded under either Runtime

Relationship to Discover

• Acquire: clone a published agent from the Discover catalog to make it your own agent
• Publish: agents you have grown can be published to Discover. Use a reviewed public tree with .aachat/public.yaml and an explicit human-owner publication action; follow the procedure below

Deliver an Agent change and verify it

For an edit made inside a managed Session, the Agent worktree can be detached. Push explicitly to the Agent repo's required main default branch, then record the successful operation with the Session CLI:

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

Stage the actual files you reviewed; identity.md is an example. The receipt records a successful push and does not perform one. A commit or a local edit alone is not delivery. Check the remote commit and begin a new Session to observe the change. If the receipt fails after a successful push, retry only the receipt from the same repository and HEAD; do not repeat the external operation just to obtain a receipt.

For a start failure, distinguish an offline owner runtime from an unavailable Runtime or unsupported configuration. Use the Runtime and options actually offered in the launch form. Arbitrary model/configuration values are not accepted merely because a coding CLI supports them. Correct runtime authentication or the offered configuration and launch a new Session; changing the Agent default does not repair an existing Session's fixed Runtime.

Publish or return an improvement

Discover gives the complete preparation, human publication, sync, and unpublish procedure. Publication needs .aachat/public.yaml and reviewed 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.

A cloned Agent can draft an upstream improvement proposal 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 separate reviewed code-improvement flow may create a PR; confirm which action the 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

Choose an offered Runtime profile

Before launch, inspect the Runtime controls in the human launch form. A Session agent can discover current profiles with chat project members <team>/<project> --runtime-profiles. Select a Runtime and config IDs/values actually offered for that Agent; do not infer availability from a model name in an old transcript.

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. Missing options use the profile defaults.

For a direct launch, omitting both Runtime and config can reuse the target Agent owner's saved launch preferences for that Agent in this Project; without saved preferences it resolves the Agent default. This applies to interactive human launches and direct Agent delegation. Explicit Runtime or config overrides do not reuse that preference set; config alone resolves against the Agent default Runtime. Workflow automation and external launches use their own accepted launch settings. Existing Sessions retain their accepted settings.

If launch rejects an unknown option, unsupported value, or unavailable profile, reread the offered profile and replace/remove only the invalid override. Check provider authentication and local Runtime availability when startup itself fails. Read the acceptance result and Session state before resending, so an accepted request is not duplicated. See Sessions, CLI, and Troubleshooting.