How to connect Meta Muse to AQ and ship code

Published October 27, 2026 · by the AQ team

Connect Meta Muse to AQ and Muse can file a work item against a real repository through AQ's REST API, start a coding CLI in an isolated Git worktree on your team's machine, and bring back the run status, preview, and any pull request the CLI opens while teammates watch and review. On its own, Meta documents Muse as a personal agent that browses the web, works in the background, and acts through Connectors, but it does not document a repository checkout, coding worktree, or pull-request review flow for the consumer agent. This guide is about Meta Muse, the personal agent on iOS, Android, and the web. It is separate from Muse Code, Meta's terminal coding CLI, which AQ can already run.

What Muse can do by itself

Meta describes Muse as a personal AI agent that can complete multi-step tasks, browse the web, use connected apps, and keep working after the app closes. Meta also lists GitHub among Muse's work connectors. That listing does not describe which GitHub operations Muse can perform, whether it clones a repository, or whether it can edit, test, commit, and open a pull request. Those capabilities are not documented for the consumer Muse app as of October 27, 2026.

Meta's Connector help says a Connector gives Muse abilities supplied by another service. If the service is absent from Muse's list, a person can ask Muse to create a custom connector. Muse guides the setup, may retrieve the service's API information, and keeps connector details in its Secure Credentials Store. Meta's approval guide says the person chooses which Connectors Muse can access, can require approval for actions, and remains responsible for reviewing what Muse does.

The useful boundary for Meta Muse coding is execution. Code in a response has not necessarily been applied to the intended branch, tested in the repository, reviewed by a teammate, or turned into a pull request. AQ supplies that execution and review path through an API Muse can call.

What changes when Muse can use AQ

This is the practical advantage of dispatching through AQ: Muse remains the personal agent that receives the goal, while a coding harness with the repository and shell does the implementation. The resulting work stays in a multiplayer coding-agent session the team can inspect.

Set up AQ as a Muse custom connector

As of October 27, 2026, Meta's consumer help pages document custom connectors built from a service's API information. They do not document a setting where a Muse user can paste a remote MCP server URL. AQ therefore has two relevant endpoints, but the verified Muse setup uses REST:

• Base URL: https://aq.dev/v1
• OpenAPI 3.1 document: https://aq.dev/v1/openapi.json

1. Create a read-only AQ key. In AQ, open Settings, then Connections, then API keys. Create a key named for this connector with only workspaces:read. API keys and the API require the AQ Pro plan.
2. Ask Muse to create the connector. Tell Muse: Create a custom connector named AQ. Use the OpenAPI 3.1 document at https://aq.dev/v1/openapi.json and the base URL https://aq.dev/v1. Authenticate with an HTTP Bearer token. Start with read-only verification and do not call a write operation.
3. Store the key through Muse's credential flow. Follow Muse's guided setup and enter the key only where Muse places it in the Secure Credentials Store. Do not put the key in an ordinary prompt, a repository, or a query string.
4. Verify with a read. Ask the connector to call GET /v1/workspaces?limit=1. A successful response proves the base URL, Bearer authentication, and workspaces:read scope without changing data.
5. Replace the test key with a narrowly scoped working key. For the workflow below, select workspaces:read, workspaces:write, agent:run, prs:read, and previews:read. Add events:read only if Muse also needs the workspace activity log.

Meta says it does not review user-created custom connectors or how they use information. A Muse connector holding an AQ key with write scopes can create work items and start coding runs as the person who minted that key. Grant the smallest scopes that complete the workflow, keep approval prompts on while testing, and revoke the key from AQ Settings if the connector is no longer needed or the key may have been exposed.

Worked example: fix a flaky test and open a pull request

Give Muse this instruction after the connector has passed the read-only test:

Use the AQ connector to find repository X, create a work item titled
"Fix the flaky test in repository X", and run my connected Codex CLI.
Have Codex reproduce the failure, make the smallest fix, run the relevant
tests, commit and push the branch, and open a pull request with the evidence.
Keep each write behind my approval. Poll until the run stops, then return the
AQ workspace, pull request, and preview URLs that AQ reports. If a result is
empty or the run needs input, tell me exactly what is missing.

The connector first uses GET /v1/repos to resolve repository X to a repo_id. The following sequence is checked against AQ's live OpenAPI document on October 27, 2026. Each POST uses a distinct Idempotency-Key; a retry of the same logical action must reuse the same key and body.

1. Create the AQ workspace

POST /v1/workspaces
Authorization: Bearer aq_your_key
Idempotency-Key: muse-flaky-test-workspace-1
Content-Type: application/json

{
  "title": "Fix the flaky test in repository X",
  "repo_id": "repo_..."
}

Save workspace.id from the 201 response. AQ assigns that work item its own Git branch and isolated worktree. A new workspace may need to be opened once in AQ before its worktree is prepared. If the run below reports workspace_not_ready, open the workspace and then resume the conversation.

2. Start the selected coding CLI

POST /v1/workspaces/{workspace_id}/agent
Authorization: Bearer aq_your_key
Idempotency-Key: muse-flaky-test-run-1
Content-Type: application/json

{
  "message": "Reproduce the flaky test, make the smallest correct fix, run the relevant tests, commit and push the branch, then open a pull request with the test evidence.",
  "source": "native",
  "native_harness": "codex",
  "native_model_id": "default"
}

This is the smallest complete selection for the connected Codex CLI in the current API. It runs on the person's own connected Codex account. To spend AQ credits instead, set source to aq and omit the three native_* fields. AQ does not automatically push or open a pull request merely because the run started; the instruction asks the coding CLI to do that, and the person's GitHub connection must allow it.

3. Poll the run and its ordered events

GET /v1/agent-sessions/{agent_session_id}
Authorization: Bearer aq_your_key

GET /v1/agent-sessions/{agent_session_id}/events?after_seq=0&limit=200
Authorization: Bearer aq_your_key

Continue while the session status is queued or running. Persist the largest event seq and send it as the next after_seq. For waiting_for_user, read the transcript and error_code before responding. Stop polling on completed, failed, or cancelled.

4. Read the pull request and preview

GET /v1/workspaces/{workspace_id}/prs
Authorization: Bearer aq_your_key

GET /v1/workspaces/{workspace_id}/previews
Authorization: Bearer aq_your_key

The pull-request list can be empty until the CLI opens a pull request and AQ tracks it. The preview list can be empty when the repository has no configured or running dev server. Muse should report those empty results as pending or unavailable, never invent a URL. The full field and error reference lives in the AQ API documentation and the live OpenAPI document.

Permissions and safety

• The AQ key is personal. It acts as the person who created it, sees only that person's accessible teams and workspaces, and carries only its selected scopes.
• Read and write are separate. Verify the connector with workspaces:read. Add workspaces:write and agent:run only when Muse should create and dispatch work.
• Retries keep the same identity. For each REST write, Muse should generate one stable Idempotency-Key and reuse it with the identical method, path, and body after a timeout. A new key represents a new action.
• Revocation happens in AQ. Removing the key from Settings stops it from authenticating. Disconnect the custom connector in Muse as a separate cleanup step.
• Muse approvals are another control layer. Meta lets people require approval before Connector actions and recommends starting with low-risk tasks, monitoring activity, and reviewing permissions. Keep AQ writes on approval while validating the connector, even when the AQ key already has the required scope.

Limits and caveats

• AQ API keys, REST access, webhooks, and MCP are included with AQ Pro. The repository must already be connected to AQ, and a native run requires the selected person's coding CLI account to be connected.
• Meta documents custom connectors and a developer connector platform that accepts API or MCP documentation. It does not currently document a consumer Muse control where a person pastes an MCP server URL. This guide therefore uses AQ's REST API. AQ's MCP server remains available for clients that document direct MCP connections.
• Meta does not document the GitHub Connector's exact scopes, a repository checkout, a coding-agent picker, a shared engineering session, or a pull-request review flow for consumer Muse. This guide does not attribute those features to Muse.
• AQ's agent start endpoint creates a conversation; it does not automatically push or open a pull request. Ask the coding CLI to do so, provide working GitHub authentication, and check the returned pull-request list.
• A newly created AQ workspace may need one browser open to prepare its worktree. A preview URL exists only when the repository's dev server is configured and running.
• Muse, Connector availability, approval controls, and subscription limits can change by account or region. Check the controls shown in the Muse app before granting a write-scoped key.

Where AQ fits

AQ is the multiplayer coding harness where engineering teams run AI coding agents like Claude Code and Codex together: shared live terminals, a code editor, and app previews, in your own cloud.

In this workflow, Muse is the front door and AQ is the engineering execution layer. Muse turns a person's goal into scoped API calls. AQ places the work on the intended repository, runs the selected coding CLI in its own worktree, preserves the session, and gives teammates one place to watch, review the diff, comment, and merge. The personal agent can coordinate coding work without pretending its own chat is a repository or asking everyone to share one local terminal.

If the team chooses Meta's coding CLI for the implementation step, read the guide to keeping Muse Code running after closing a laptop. Muse Code remains distinct from the Meta Muse personal agent that called the AQ API.