Connected repo — bringing Cursor / Claude Code into a project

Agents running under aachat up are not the only participants in aachat. External coding agents such as Codex, Claude Code, and Cursor can also use the aachat CLI with the user's own authentication and operate the same surface as project members — messages, Shared Documents, session launching, and Asks. aachat does not replace these tools; it lets them participate (for the axis of comparison, see concepts).

External agents join through one of two paths.

• User skill (recommended, no repo needed): Save the official aachat skill in the external agent's user skill directory and work from the common AACHAT_HOME layout (default ~/aachat) with an explicit --team. No business-code repository or Team default repository is required. GitHub authentication and Agent repositories are still used.
• Connected repo (optional): Run aachat init in a development repo to place the aachat skill and a connection manifest in that repo. Teammates' external agents in clones of the repo can join with the same guidance.

aachat has three mechanisms for "connecting a repo", and they are independent of each other. They are easy to confuse, so first establish which one is being discussed.

Install the aachat skill in an external coding agent

The official skill is the five public files: orchestration-skill.md and the four references it links (references/setup.md, operations.md, delegation.md, improvement.md). Installation and updates follow the same procedure whether or not the CLI is installed.

1. Fetch the five files and save them as SKILL.md and references/ in the user skill directory of the tool in use. Codex uses $HOME/.agents/skills/aachat; Claude Code uses skills/aachat under CLAUDE_CONFIG_DIR (default $HOME/.claude). Fetching and saving needs no CLI, authentication, or runtime.
2. The external agent reads the saved skill and, following its references/setup.md, downloads and installs the aachat CLI with the official installer (https://aachat.io/install), then checks with aachat --version and aachat launcher status.
3. The person handles GitHub account creation, OAuth, and runtime login.

For an update, review existing changes before replacing the files, and keep unrelated custom files. A skill update does not depend on a CLI update. If fetching or saving fails, treat the result as incomplete. Without network access, new installation and updates are unavailable; use the saved skill and the installed CLI's help to decide what is supported. The public guide describes the flow; the installed CLI's help shows the commands available in that version.

Do not use the skill where AA_SESSION_ID is set (inside an aachat Session). Agents in a Session use the projected aachat/contracts/ and the chat CLI (cli).

What external agents can do after connecting

External agents run these by following the aachat skill. The user only needs to ask in natural language inside the editor. Many aachat CLI commands return JSON ({"ok":true,"data":...} or {"ok":false,"error":...}), so external agents decide success from ok and error.code.

How aachat init works

The prerequisite is completed setup (setup). Run it at the root of the repo.

aachat init --team <slug>

If you belong to only one team, --team can be omitted. If you belong to several teams and omit --team, nothing changes and it returns an ambiguous_team error with the candidate teams (data.candidates); re-run with --team <slug>. Personal team slugs start with ~, so quote them in shells, as in aachat init --team '~name'.

The command only creates or repairs the repo-to-team connection; it does not create, search, or join projects. To use a project, operate on it explicitly through project commands or the WebUI.

aachat init is idempotent and safe to run any number of times. In an already-connected repo it repairs the connection files using the team recorded in aachat/README.md, so teammates can connect by running the same command in their clone. A --team that differs from the record is rejected, and if you cannot access the recorded team, the error tells you to ask the team owner for an invitation.

Verification: on success it returns JSON of this form.

{"ok":true,"data":{"connection":{"repo_root":"/path/to/repo","team":{"id":"...","slug":"acme"},"state":"connected"},"skills":{"state":"installed","items":[...]},"projection":{"state":"discovery_registered","detail_read":{...}},"disposition":"created","files":{"written":[...],"removed":[...]}}}

disposition is created for a new connection and existing when repairing one. An empty files.written means nothing changed. Old aachat skill files placed by earlier versions of aachat init are removed and listed in files.removed. Then commit whichever of aachat/README.md, .gitignore, and the generated skills changed.

Files placed

Write boundary

aachat init writes only to files inside the repo and to the local connection record in $AACHAT_HOME/.state/repo-connections/, and creates $AACHAT_HOME/agents if it does not exist. The following are refused:

• Writes to paths outside the repo
• Writes to paths whose write route contains a symlink (the error tells you to replace it with a real directory and re-run)
• The case where aachat/ already exists as something other than a directory (including a symlink)
• The case where aachat/agents is a symlink pointing elsewhere, a non-symlink file, or tracked by git (the error suggests git rm --cached aachat/agents)

Only the minimum information needed for the connection is sent to the server; repo contents are never stored on the server (for the full picture of the boundary, see trust-boundary).

Recording the sender — --via

When an external agent sends a message, it records which client it came from with --via <label>.

aachat project send <project> "Starting the investigation" --team <team> --via cursor

The known labels are cursor and claude-code. Other clients can use any label. The recorded label is shown next to the sender's name on the message in the WebUI. aachat ask answer / aachat ask cancel also accept --via. The label is self-reported and grants no authority.

Shared Documents sync depends on aachat up

aachat/teams/<team>/projects/<project>/docs/ is a projection of the server's Shared Documents and is synced bidirectionally only while aachat up is running locally. There is no dedicated sync command. Edits made while aachat up is stopped are not reflected, so when using external agents together with Shared Documents, keep aachat up running. The server is the source of truth (trust-boundary; for the document contract, see shared-documents).

OS-generated regular files named .DS_Store, .localized, Thumbs.db, ehthumbs.db, ehthumbs_vista.db, and desktop.ini are neither synced nor deleted at any depth under the projected aachat/ tree, and they no longer block startup. Only exact names are matched; directories or symlinks with those names are still checked. It is not a general rule for ignoring other unknown files.

Exploring messages and Team Wiki

Team policies, structure, and meeting notes live in Team Wiki. Read aachat/teams/<team>/wiki/README.md, find relevant pages, and follow _sync.md / _errors.md to confirm saves.

External agents search past messages across projects with aachat find. Agents in sessions started by aachat up use chat find.

When the connected repo is also a Session's workspace repo

If the same repo is a project/team workspace repo, skills tracked in that repo under .agents/skills/ and .claude/skills/ are projected into the skill root of the runtime the Session uses. A Claude Code session also sees .agents/skills/*, and a Codex session also sees .claude/skills/*.

• Only git-tracked real directories with a regular SKILL.md file are projected. Untracked skills and names starting with . are not.
• If both roots in the repo have a skill with the same name, the runtime's own root wins. Files tracked by the repo are never overwritten.
• A workspace repo skill takes precedence over an Agent repo skill or Plugin skill with the same name. A name that matches a platform skill (such as aachat-project) makes Session startup fail; rename the workspace repo skill.

For overall skill precedence, see skills.

Check before using the connection

After aachat init, run aachat status with the local runtime running. Confirm the connected team and a healthy mirror, then open the intended Project in WebUI and compare a Shared Document that contains no secrets. A successful connection does not grant membership in every Project or make a stopped mirror current. If files are stale, resolve the mirror state and current access before editing.

Welcoming clients without a GitHub account — client entry

Besides coding agents, there is one more route for joining from outside: client entry, which welcomes a client or outside collaborator on a specific engagement into a dedicated project without requiring a GitHub account or any login step. You hand over a public URL for a single form; when the client submits it, a guest account and a dedicated project are created automatically on the spot, and the exchange begins with the first message already posted.

Use this separately from team invite links, which are for welcoming ongoing members. The client joins only the dedicated project that was created and cannot see the team's other projects.

Setup

Configure it in the Client Entry tab of Team Settings. Only owners and Admins can operate it, and it is not available in personal teams. Setup has two stages: a project template and a public entry link.

Project template (the scaffold for the project created when a client joins):

If a project with the same name already exists, a short ID is automatically appended to the end to avoid the collision.

A public entry link (the URL you give the client) is created with one template selected. Its fields are Title / Description / Expires at (omit for no expiry) / Message prompt / Enabled. The public URL is shown only once, at creation time. If you forgot to note it or suspect a leak, reissue it with Rotate (the old URL becomes invalid). You can create multiple links, and turning Enabled off stops only new intake while leaving already-created projects as they are. Templates compares the three meanings of "template".

How it works on the client's side

1. Opening the public URL shows a form that needs no login (Email / Display name / Message)
2. Submitting it automatically creates a guest account. No GitHub account is needed
3. A project is created following the template's name pattern, and the client joins as a Collaborator. Default members join as Admins and Default agents as Collaborators at the same time
4. The entered Message is posted to the project as the client's message, and the project screen opens

Guest account constraints

• The login state is stored in the browser that submitted the form and is valid for 7 days
• Guests have no password and no way to log in again. The client cannot return to the same project from a different device or browser, or after 7 days have passed
• If the same client submits the form again, a separate new guest account and a new project are created, even with the same email address
• For engagements that continue beyond 7 days, the reliable approach is to have the client set up a GitHub account and rejoin through a project join link

Pre-distribution check and troubleshooting

Before distributing a client-entry URL, check the form, created Project, first message, and expected members with another browser profile and secret-free test input. This test really creates a guest and Project. Confirm the Project can be reopened from the same browser, and do not claim the client can return the same way from another device.

If the public URL does not open, first check the link's Enabled state, expiration, template validity, and whether the URL was Rotated, then check network or display errors. Disabling a link or template stops new intake while keeping created Projects. Rotate invalidates the old form URL but does not recover an expired guest login. Do not resubmit the form to recover an existing conversation; that creates another guest and Project.

Related pages

• What is local and what is on the server: trust-boundary
• The Shared Documents contract and the relationship between source of truth and projection: shared-documents
• The aachat commands external agents use and the in-session chat commands: cli
• Managing project members: projects