---
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.md).

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.md`) |
| Repository tree | The GitHub App integration in team settings | Showing a read-only file tree in the WebUI sidebar (`webui.md`) |

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

## What `aachat init` does

Prerequisite: setup is complete (setup.md). 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. Connecting guarantees participation in the team's connection project `setup` (it is created if it does not exist).

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

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/` and `.agents/skills/aachat/` | The aachat skill set read by Claude Code / Cursor via their respective skill discovery paths (`SKILL.md` plus references for messaging / documents / media / html / agents / asks) |
| `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.md).

## 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.md; the document contract is shared-documents.md).

## Searching past messages

aachat bundles the MCP server `aachat-mcp`, which is automatically wired into sessions started by `aachat up` (no manual setup). The cross-project past-message search tool is one of 17 tools it provides: `aachat_search` (Concept, Entity, and OKR are out of scope; see `cli.md` for the full tool list). External agents working in a connected repo perform the same search with `aachat find`.

## 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", the cause is one of: the link's Enabled is off, the link has expired, or the template is disabled.

## Related pages

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