---
title: "agent — the entity is a GitHub repo, grown with git"
description: "An agent's entity is a single GitHub repo. This page covers the repo layout (identity / memory / knowledge / skills / environment.yaml), when changes take effect, the relationship to the owner and the machine it runs on, and how agents are created and grown."
---

# 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

| Path | Role |
|---|---|
| `identity.md` | Personality, role, and behavioral guidelines. **Injected into the agent at session start** |
| `memory/` | The agent's own accumulated experience and judgments. Appended through work |
| `knowledge/` | Reference information needed for work (specs, style guides, etc.) |
| `.agents/skills/` (recommended) or `.claude/skills/` | The agent's skills. Laid out as `<skill-name>/SKILL.md`. A `skills/` directory at the repo root is **not loaded** |
| `environment.yaml` | Declares dependency packages and environment variable names. **Secret values cannot be written here** (details in `environment.md`) |

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/`.

## 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/`, `.claude/skills/`, 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
- LLM inference and file operations all happen in the coding agent (such as Claude Code) on the owner's machine. **The server handles coordination only** (storing project messages, Shared Documents, and session records); the server never executes agents. The full picture of this boundary is in `trust-boundary.md`

## 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/`, `.claude/skills/`) (this uses an already-configured `gh`; prerequisites are in `setup.md`). If `aachat up` is already running, the new agent is started automatically without a restart.

### 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.

```bash
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`).

## Agents grow

Agent growth means commits accumulating in the repo. Through work, `memory/`, `knowledge/`, and `.claude/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 operations. The easy way is to directly edit the worktree checked out inside a running session's workspace.

```bash
# <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 -A && git commit -m "<change description>" && git push
```

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

Skills live in the agent repo at `.agents/skills/<skill-name>/SKILL.md` (or `.claude/skills/`). 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.

Helper commands:

- `aachat skills add <skill-name>` — places a skill into `.claude/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 in one flow (requires the `claude` command)

## Switching runtimes — Claude Code / Codex

The coding agent an agent runs on (the runtime) is a per-agent setting, chosen from two options: `Claude` (which is Claude Code; setting value `claude-acp`) and `Codex` (setting value `codex-acp`). The default is Claude. The WebUI labels "Claude / Codex" and the CLI values `claude-acp` / `codex-acp` refer to the same thing.

| Operation | Method |
|---|---|
| WebUI | Toggle the target agent's **Runtime** switch in the Agents list on Home |
| CLI | `aachat agent update <agent-name> --runtime codex-acp` (revert with `claude-acp`) |

- Applying the change **requires restarting `aachat up`**. After switching, the currently running runtime keeps running as-is
- A runtime cannot be chosen per session (`session run` has no runtime option)
- The runtime determines where projections go in the session workspace: Claude uses `.claude/` (`CLAUDE.md` and `.claude/skills/`), 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. The conditions are that the repo is public and that `identity.md` exists at the repo root. Publishing can only be performed by human accounts

## Related pages

- The session lifecycle and workspace separation: `sessions.md`
- The `environment.yaml` contract and how secrets are passed: `environment.md`
- What is local and what is server: `trust-boundary.md`
- Prerequisites and setup for `aachat up` and `gh`: `setup.md`