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

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.

What external agents can do after connecting

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.

What aachat init does

Prerequisite: setup is complete (setup). Run it at the repo root.

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

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

Recording the sender — --via

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

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; the document contract is 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):

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

External coding agents can read the current outside-agent contract at orchestration-skill.md. This is the operation entry point linked by the generated skill; the public guides explain the user journey. Keep generated connection instructions rather than copying old command lists into new local guidance.

Related pages

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