FAQ

General

What is ClosedLoop.ai?

A spec-driven, AI-first delivery platform. It combines a browser-based control plane, a desktop client with a localhost gateway, and six Claude Code plugins into one system that turns scoped artifacts into shipped code through gated loops.

How is this different from a chat-based coding workflow?

Chat optimizes for local velocity. ClosedLoop.ai optimizes for organizational leverage. Every run is bound to a durable artifact, gated by deterministic validation, scored by judges, and captured back into organizational patterns. See ClosedLoop.ai vs chat-based workflows.

What does "closed loop" mean?

A loop is closed when its output is tied back to its input. In ClosedLoop.ai, every agent output is grounded in and graded against the artifact that launched the run.

Install and setup

Do I have to install everything?

Yes, if you want the full experience. The plugins provide the orchestration; the desktop client provides the execution surface. You can run the plugins alone in Claude Code without the desktop client, but you lose the web control plane, approvals, and safe cross-machine execution.

Does it run on Linux or Windows?

• macOS — fully supported; packaged DMG.
• Linux — supported for development via just desktop-dev; not packaged.
• Windows — not supported for the desktop client.

What Python version do I need?

Python 3.11+ (3.13 recommended).

What about PATH issues with claude, git, gh, etc.?

The desktop client spawns $SHELL -ilc with sentinels to extract your login shell PATH. If that does not work, override specific binaries at Settings → Binary paths.

Security

Where is my API key stored?

Encrypted via Electron safeStorage (operating system keychain) in desktop-secrets.json. Environment variables (CLOSEDLOOP_API_KEY, then SYMPHONY_API_KEY) take precedence over the stored value.

Can the web app access anything outside my sandbox?

No. Every path is filtered through isPathAllowed. Only paths under your sandboxBaseDirectory are touchable, and certain paths are hard-denied even inside the sandbox (see Approvals and sandbox).

Does the desktop need an inbound port open?

No. The cloud relay is outbound-only. The desktop maintains a Socket.IO connection to https://relay.closedloop.ai; nothing listens for incoming public traffic. The localhost gateway on port 19432 is bound to 127.0.0.1 and requires auth.

How do I disable gateway auth for testing?

Do not, unless you are in a dev environment. Set CL_LOCAL_GATEWAY_NO_AUTH=1 (dev-only, blocked in packaged builds). Prefer CL_LOCAL_GATEWAY_DEBUG_AUTH=1 to mint short-lived tokens for curl tests.

Loops and plans

How long does a loop take?

Small loops (unit test, doc edit) complete in minutes. Feature-sized loops take tens of minutes. The CLOSEDLOOP_MAX_ITERATIONS cap (default 10) bounds the worst case.

What happens if the plan is wrong?

Use /code:amend-plan with a directive to adjust. The amend extractor classifies your input (directive, question, confirmation, unstructured) and updates plan.json accordingly.

Can I skip judges?

Yes, though you lose the scoring signal. Judges run automatically inside the code loop and can be triggered manually with @judges:run-judges.

How do I stop a running loop?

/code:cancel-code removes the state file. The desktop client will also kill the process group on cancel commands.

Judges and review

Are judge scores reliable?

Judges are LLMs, so scores are not perfectly deterministic. They are reliable in aggregate — you should look at trends across judges, not single points. The default threshold is 0.8, overridable per metric.

Can I add my own judges?

Yes. Judges are agent files with YAML frontmatter and a prompt. Drop one into plugins/judges/agents/, add it to the batch configuration in run-judges, and it will run. See the existing judges for the CaseScore output shape.

What is the difference between critics and judges?

• Critics run before implementation to improve the plan.
• Judges run after implementation to grade plan, code, or PRD quality.

Both are LLM-driven, but they sit at different points in the loop.

Self-learning

Does self-learning share my code?

Only the patterns you capture are shared — not raw code. Pattern citations reference file paths but not content. /push-learnings and /pull-learnings sync pattern metadata, not source.

How do I reset learnings?

Delete .learnings/ in a project to reset per-project state, and ~/.closedloop-ai/learnings/org-patterns.toon to reset user-level patterns. Keep a backup if you have captured valuable patterns.

How often should I run /process-learnings?

The code loop runs it automatically after every iteration. Run it manually when you want to promote pending learnings explicitly.

Integrations

Does it work with Codex?

Yes. Codex is supported as a chat provider and as a plan debate partner. See Refine a plan with Codex.

Does it work with GitHub?

Yes. The gateway exposes git_pr operations that use gh under the hood for PR creation, comments, reviews, and inline annotations.

Can I run it without GitHub?

Yes. The code loop produces diffs and can commit locally. The git_pr operations just will not be usable.

Contributions

Where do I file bugs?

Use the repository issues for closedloop-ai/closedloop-electron and closedloop-ai/claude-plugins.

Where is the source?

• Desktop client: closedloop-ai/closedloop-electron on GitHub.
• Claude Code plugins: closedloop-ai/claude-plugins on GitHub (Apache 2.0).

How do I propose a new judge or agent?

Open a PR with the new agent file and the necessary wiring (critic gates, batch config, or skill frontmatter). Follow the style in existing files and include tests for any Python tooling you change.