---
title: "Connected repo — bringing Cursor / Claude Code into a project"
description: "The mechanism for connecting a development repo to a team with `aachat init` so that external coding agents working in it can join projects. Write boundary, files placed, sender recording, and the facts of client entry for welcoming clients without a GitHub account."
---

# Connected repo — bringing Cursor / Claude Code into a project

Agents running under `aachat up` are not the only participants in aachat. When you connect a development repo to a team with `aachat init`, external coding agents such as Cursor / Claude Code working in that repo can 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](/en/docs/concepts)).

A connected repository is optional. Codex and Claude Code first fetch and save the five public files linked from the [official aachat skill](https://aachat.io/orchestration-skill.md) in their user skill directory. The external agent then reads the saved skill and follows its setup instructions to download and install the aachat CLI with the official installer. Skill installation uses this same public download-and-save procedure even when the CLI is already installed. Agents can work with the common `AACHAT_HOME` (default `~/aachat`) projection using an explicit `--team`. The CLI installer and skill do not require a business-code repository or Team default repository; GitHub authentication and Agent repositories are still used.

This connection is a separate mechanism from the GitHub App integration configured in the WebUI team settings and from the agent's working repo setting. It is completed with only the local repo and the aachat CLI; no GitHub-side configuration is needed.

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.

| Mechanism | How it is configured | What it is for |
|---|---|---|
| Connected repo (this page) | `aachat init` in the repo | Bringing external coding agents working in that repo into projects |
| workspace repo | project / team settings, `session run --repo` | Determining the repo checked out into a session's workspace ([sessions](/en/docs/sessions)) |
| Repository tree | The GitHub App integration in team settings | Showing a read-only file tree in the WebUI sidebar ([webui](/en/docs/webui)) |

## What external agents can do after connecting

| Goal | Operation |
|---|---|
| Report and share to a project | `aachat project send` (record the sender with `--via`) |
| Check new messages and mentions addressed to you | `aachat inbox` / `aachat mentions` |
| Delegate work to an agent on aachat | `aachat session run` / `aachat session send`. The target agent must be a member of the target project |
| Search past conversations | `aachat find` (cross-project message search) |
| Persist deliverables and specs as the source of truth | Edit Markdown under `aachat/projects/<team>/<project>/docs/` directly (synced as Shared Documents) |
| Ask a human for a decision or approval | Host ask in this conversation. Use `aachat ask list|show|answer|cancel` for existing project Asks |
| Place browser-checkable deliverables | Put static files under `aachat/projects/<team>/<project>/html/` |

External agents perform these by following the guidance of the placed skill (described below). The user only needs to make requests in natural language inside the editor.

Note that agents inside sessions started by `aachat up` use the dedicated `chat` CLI, not this surface. For in-session operations, see [cli](/en/docs/cli).

## What `aachat init` does

Prerequisite: setup is complete ([setup](/en/docs/setup)). Run it at the repo root.

```bash
aachat init
```

If you belong to multiple teams, a selection prompt appears. `aachat init --team <slug>` specifies the team directly. The command only creates or repairs the repo-to-team connection; it does not create, search for, or join projects. Use the project commands or WebUI when you want to work with a project.

`aachat init` is idempotent and safe to run any number of times. On an already-connected repo it repairs the existing connection files, so teammates can connect a cloned repo by running the same command.

Success check: `✓ Connected this repo to aachat` is displayed. Following the guidance, commit `aachat/README.md`, `.gitignore`, and the generated skill.

## Files placed

| Destination | Content |
|---|---|
| `aachat/README.md` | Connection manifest. Connected team information and usage rules for external agents |
| `.claude/skills/aachat/SKILL.md` and `.agents/skills/aachat/SKILL.md` | The same official aachat skill bundle for Claude Code and Codex / compatible agents. Each root includes `SKILL.md` and `references/{setup,operations,delegation,improvement}.md`, with the same canonical content served by public HTTP |
| `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.github/copilot-instructions.md` | aachat guidance appended as a managed block, only to files that already exist |
| `.gitignore` | Excludes `aachat/*` from git (with `!aachat/README.md` as the only exception) |
| `aachat/agents` | Symlink to `~/aachat/agents` (Unix / WSL only) |

## Write boundary

`aachat init` writes only to files inside the repo and to the local connection record in `~/aachat/.state/repo-connections/`. The following are rejected.

- Writes to paths outside the repo
- Writes to paths whose write path contains a symlink (the error instructs you to replace it with a real directory and rerun)
- Cases where `aachat/` already exists as something other than a directory (including a symlink)

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

## Recording the sender — `--via`

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

```bash
aachat project send <project> "Starting the research" --via cursor
```

The known labels are `cursor` and `claude-code`. Other clients may use any label. The recorded label is displayed next to the sender name in the WebUI Timeline, like `(cursor)`.

## Shared Documents sync requires `aachat up`

`aachat/projects/<team>/<project>/docs/` is a projection of the Shared Documents on the server, and it syncs 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 combining external agents with Shared Documents, keep `aachat up` running. The source of truth is the server side ([trust-boundary](/en/docs/trust-boundary); the document contract is [shared-documents](/en/docs/shared-documents)).

## Exploring messages, Team current state, and Meetings

External agents working in a connected repo search past messages across projects with `aachat find`. Agents inside sessions started by `aachat up` use `chat find`. Message search is not an `aachat-mcp` responsibility.

While `aachat up` is running, the connected repo receives the same Team current-state paths as a session: `aachat/teams/<team>/{concepts,entities}` plus the 50 most recent Meeting bodies under `aachat/meetings/`. Before company-context-dependent work, check `aachat status` and require `daemon.workspace_mirror.team_projection.state` to be `healthy`. When it is `unavailable`, `revoked`, or `stopped`, remaining files may be stale; follow the blocker instead of reading them as current.

Read the two Registry `_index.yaml` files first, open only the relevant individual YAML, then search Meeting bodies by the selected names. Individual Registry YAML is editable, but saving it only stages a local change. Validate and send one native operation with `aachat registry check / plan / submit`; clean files can be updated with `aachat registry refresh`. Indexes and Meeting Markdown are generated and read-only. Session agents use the same filesystem schema with `chat registry` and session authority. `aachat-mcp` still provides only the 3 tools for reading Concept reviews, posting a review, and proposing removal.

## Welcoming clients without a GitHub account — client entry

There is one more entry path from the outside besides coding agents: client entry, which welcomes a client for a specific engagement or an external collaborator into a dedicated project without requiring a GitHub account or any login step. You hand over a public URL to a single form; when the client submits it, a guest account and a dedicated project are created on the spot, and the conversation starts with the first message already posted.

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

### Configuration

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

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

| Field | Content |
|---|---|
| Name | Administrative name of the template |
| Project name pattern | Pattern for the created project name. Can combine `{date}` / `{display_name_slug}` / `{short_id}` |
| Template enabled | When off, stops new project creation from this template |
| Default members | Team members who join automatically. They are added as project Admins. If empty, the link creator joins as Admin |
| Default agents | Agents that join automatically. They are added as Collaborators |

If a project with the same name already exists, a short ID is automatically appended and the collision is avoided.

The public entry link (the URL you hand to 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 displayed only once, at creation time.** If you forgot to save it or suspect a leak, reissue it with Rotate (the old URL becomes invalid). Multiple links can be created, and turning Enabled off stops new submissions only, leaving already-created projects intact.

### What the client experiences

1. Opening the public URL shows a form (Email / Display name / Message) that requires no login
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 another device, another browser, or after the 7 days
- If the same client submits the form again, a new separate guest account and a new project are created even with the same email address
- For engagements longer than 7 days, the reliable approach is to have the client prepare a GitHub account and rejoin via a project join link

If a client "cannot open the link", first check whether the link is disabled, expired, rotated, or its template is disabled.

## Check the connection and client intake before relying on them

After `aachat init`, run `aachat status` with the local runtime running. Confirm the connected team and healthy mirror, then open the intended Project in the WebUI and compare a non-sensitive Shared Document. 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 them.

The two Registry indexes are `aachat/teams/<team>/concepts/_index.yaml` and `aachat/teams/<team>/entities/_index.yaml`. For a concrete Registry editing example, use [Concept Registry](/en/docs/concept-registry); saving projected YAML stages a change that still needs check, plan, and submit. Meetings are read-only snapshots, not a third editable Registry.

Before distributing a client-entry URL, use a separate browser profile and non-sensitive test data to verify the form, created Project, first message, and intended members. This test creates a real guest and Project. Check the same browser can reopen that Project; do not promise the same result from a different device. A long-term client should join the intended existing Project with a GitHub account and its Project join link before the guest login expires.

If the public URL fails, first check Enabled, expiry, template availability, and whether the URL was rotated; also inspect connectivity or the displayed error. Disabling a link or template stops new intake, while created Projects remain. Rotating the link invalidates the old form URL and does not restore an expired guest login. Do not resubmit the form as a recovery method for an existing conversation: it creates another guest and Project. The three meanings of template are compared in [Templates](/en/docs/templates).

External coding agents install and update their user skill by fetching [orchestration-skill.md](https://aachat.io/orchestration-skill.md) and its four linked references and saving them in the same user skill directory. Codex uses `$HOME/.agents/skills/aachat`; Claude Code uses `skills/aachat` under `CLAUDE_CONFIG_DIR`, otherwise `$HOME/.claude`. Review existing edits before replacing these files and preserve unrelated custom files. Updates do not depend on CLI updates. If fetching or saving fails, installation or update is incomplete; without network access, only an already saved skill and installed CLI help are available. The public guides explain the user journey; the installed CLI help determines which commands that version supports.

## Related pages

- What is local and what is on the server: [trust-boundary](/en/docs/trust-boundary)
- The Shared Documents contract and the source-of-truth / projection relationship: [shared-documents](/en/docs/shared-documents)
- The `aachat` commands used by external agents and the in-session `chat` commands: [cli](/en/docs/cli)
- Project member management: [projects](/en/docs/projects)