How to for using cursor with aidc

[anantshri]

cursor gui would obviously run in main system but we need to document exact commands and config to make the sytem be the base for cursor code execution part.

[ai-anant]

🤖 Watchdog analysis

Title: How to for using cursor with aidc (#26)

Root cause

aidc already ships two distinct Cursor entry points, but neither fully answers "make aidc's container the base for Cursor GUI code execution":

1. aidc cursor-agent (CLI/headless path) — already works in-container.
   lib/aidc.sh:755-757 → aidc::run_tool "cursor-agent", and lib/aidc.sh:916-918 runs cursor-agent --sandbox disabled -f inside the container. cursor-agent is installed into the image by templates/devcontainer/Dockerfile.tmpl:214 (curl -fsS https://cursor.com/install | bash), with its state volume cursor_agent_home mounted at /home/vscode/.cursor-agent.

2. aidc cursor (GUI path) — lib/aidc.sh:759-767 opens the host Cursor GUI on the workspace and advises "reopen the repo in the devcontainer using the Remote Containers extension".

The GUI + Dev Containers path is where it breaks today. The generated .devcontainer/devcontainer.json.tmpl is a compose-based devcontainer:

{
  "dockerComposeFile": "compose.yaml",
  "service": "workspace",
  "workspaceFolder": "/workspace",
  "runServices": [],
  "overrideCommand": false,
  "shutdownAction": "stopCompose",
  ...
}

And compose.yaml.tmpl interpolates host-side vars that aidc defines when it runs docker compose itself:

• ${AIDC_WORKSPACE} (bind → /workspace)
• ${AIDC_DEVCONTAINER_DIR} (read-only overlay → /workspace/.devcontainer)
• ${AIDC_CORE_LOGICS_WORKTREE} (→ /opt/CORE_LOGICS)
• ${AIDC_HOST_SEED_CLAUDE|CODEX|OPENCODE|GROK} (→ /host-seed/*)
• ${AIDC_GITCONFIG_SOURCE} (→ /host-seed/gitconfig)
• ${AIDC_CLIPBOARD_DIR_SOURCE} (→ /host-clipboard)
• ${AIDC_TOOLCHAINS} / ${AIDC_SECURITY_TOOLS} (build args)

If the Cursor GUI's Dev Containers extension launches this compose stack on its own, none of those vars are set in its environment, so they expand to empty strings. Compose then fails to create the bind mounts (e.g. an empty source:), the read-only .devcontainer overlay won't resolve, and the rebuild loses the toolchain/security build args. In other words: a bare "Dev Containers: Reopen in Container" from the GUI cannot work today without aidc orchestrating the env.

There is also a lifecycle collision to design around: devcontainer.json sets shutdownAction: stopCompose and overrideCommand: false, and the compose command runs bootstrap-state.sh init && sleep infinity. If the GUI also manages the same workspace service, its stop-compose semantics could tear down the very container aidc is managing.

So the missing deliverable is real and non-trivial: a documented, reproducible way to attach the Cursor GUI to aidc's container (or a self-contained GUI devcontainer), plus the config to make that safe.

Existing PR status

No open pull request addresses this issue. All currently open PRs (#14–#23) target image sizing, in-container script behavior, and toolchain volumes — none documents the Cursor GUI + Dev Containers integration. (Some bodies merely mention the word "cursor" incidentally.)

Fix guidance

This is a documentation + possibly small-code task. It needs a design decision first, so I've kept it as guidance rather than guessing a PR. Two credible paths:

Path A — Cursor CLI agent inside the container (document; already works)

This is the most complete "code execution lives in the container" story today and is the simplest to document:

cd /path/to/repo
aidc up                 # ensure container running
aidc cursor-agent       # cursor-agent runs INSIDE the aidc container at /workspace

• --sandbox disabled -f is already the default (see lib/aidc.sh:917), matching how the other agents are run (--dangerously-skip-permissions, etc.) — the container is the isolation boundary.
• State persists in the cursor_agent_home volume → /home/vscode/.cursor-agent (compose.yaml.tmpl).
• Document pass-through of extra args: aidc cursor-agent -- <your-flag> (the run_tool appends "$@").

Suggested docs update: a new docs/cursor.md section (or an install.md subsection) titled "Cursor — CLI agent (in-container)" covering aidc cursor-agent, the default flags, where state lives, and how it differs from the GUI path below.

Path B — Cursor GUI with container execution (needs a small design fix first)

The GUI (host) renders the editor, but you want terminal/build/run/agent execution to happen in the aidc container via the Dev Containers extension. Because of the env-var dependency in compose.yaml.tmpl, pick one of these and implement it before/while documenting:

• Option B1 — document an env-export launcher (no code, but fiddly): export the AIDC_* vars in the shell that launches Cursor so the Dev Containers extension inherits them, e.g. a small aidc env-style helper that prints AIDC_WORKSPACE, AIDC_DEVCONTAINER_DIR, AIDC_CORE_LOGICS_WORKTREE, the AIDC_HOST_SEED_*, AIDC_GITCONFIG_SOURCE, AIDC_CLIPBOARD_DIR_SOURCE values for the current repo, then eval "$(aidc env)" && cursor /path/to/repo. Verify the resulting compose has non-empty bind sources before trusting it.
• Option B2 — a self-contained GUI devcontainer (recommended, cleaner): generate a second devcontainer config for the GUI that does not depend on host AIDC_* vars, either:
  • pointing at the already-running aidc container/image ("image": "<aidc image>" + the same volumes and /workspace mount), or
  • a plain dockerFile/dockerComposeFile with in-file defaults for workspace path and seed locations.
    This decouples Cursor from aidc's env and avoids the stopCompose/overrideCommand lifecycle collision.

Whatever is chosen, the doc must make explicit: the CLI agent and GUI paths are independent, and do not let the GUI's Dev Containers stopCompose manage the container that aidc up/aidc down own.

Decision needed from the maintainer: which option (B1 vs B2) is the intended supported path. That decision gates an accurate docs/cursor.md. If B2 is chosen, it is a small, contained template addition (a few dozen lines in templates/) and becomes a legitimate small PR.

PR status

No new PR opened. This issue is guidance-only for now because the correct integration requires the maintainer to pick an approach (document-only env-export vs. a self-contained GUI devcontainer template), and guessing the wrong one would produce inaccurate documentation or a conflicting compose lifecycle. No existing PR covers it, so once the approach is chosen this is a clean, small doc/template PR.

Verification

• Verified aidc cursor-agent → run_tool "cursor-agent" → cursor-agent --sandbox disabled -f (lib/aidc.sh:755-757, 916-918).
• Verified cursor-agent install + ~/.cursor-agent volume (templates/devcontainer/Dockerfile.tmpl:209-215, compose.yaml.tmpl).
• Verified devcontainer.json.tmpl is compose-based (dockerComposeFile: compose.yaml, shutdownAction: stopCompose) and that compose.yaml.tmpl interpolates host AIDC_* vars — the root blocker for GUI reopen-in-container.
• To run yourself: aidc status after aidc init in a test repo, then attempt cursor GUI reopen-in-container and confirm the compose env vars are populated; capture the exact compose error for the chosen fix.

Pre-1.0 API note: aidc is rolling-release/alpha; doc guidance here is based on the current main (commit ee2939a).