Cloud Agent

The cloud agent runs CodeLantern skills for you when no one has a coding session open. You mention @codelantern-ai with a command on a GitHub issue or pull request, and a run starts in your repository's own GitHub Actions. It works on the same issue, branch, and pull request you would, then reports back in a comment.

Use it for steps that don't need you at the keyboard, such as drafting a plan for a spec'd issue or building an approved plan. Interactive skills, such as spec or design-solution, stay local because they need your answers.

What you need

• A GitHub repository with issues tracked in GitHub. The cloud agent runs in GitHub Actions and listens for comments on GitHub issues and pull requests. For a command that starts a run from a pull request, its description must reference an issue in the same repository with Closes #42, Fixes #42, Resolves #42, or Implements #42. This is required for /review too; without that reference, the run fails before it reaches the command.
• The CodeLantern GitHub App installed on the repository, and the repository registered in the portal with an active configuration.
• GitHub Copilot allowed in GitHub Actions for your GitHub organization. The run uses your organization's Copilot plan. You don't create or store any tokens or secrets for it.
• Dependencies that install on a clean Linux runner. Each run installs your project's dependencies on a GitHub-hosted Ubuntu runner with Node.js 22, from your lockfile, without any secrets. A project that needs a private registry or an install-time secret can't build in a run. Each run has a 60-minute limit.
• The workflow on your default branch. GitHub starts these runs from the workflow file on the repository's default branch, so a workflow that exists only on another branch never runs.

Turn it on

1. Run /cl-dev:cl-init in the repository and answer yes when it offers the cloud agent. It adds .github/workflows/cl-dispatch.yml and .github/scripts/run-agent.mjs. If you skipped it the first time, run cl-init again and accept it.
2. Commit both files and merge them into your default branch.
3. Confirm the prerequisites above with whoever manages your GitHub organization.

To turn it off, delete those two files from the default branch.

Delegate work

Post a new comment on an issue or pull request that mentions @codelantern-ai, followed by a command. Edited comments don't start a run.

For example, to draft a plan for a spec'd issue:

@codelantern-ai /architect

You don't need to claim the issue first. /architect claims it as part of the run. /implement accepts a plan that's ready but not yet approved and approves it as it starts, so run /approve-plan first, or approve the plan yourself, if you want to review it before any code is written.

Use one of the commands listed above and check its spelling before posting.

Only people who are repository owners, organization members, or collaborators can start a run. Comments from other people and from bot accounts are ignored. A run assigns the issue or pull request to you and commits under your GitHub username.

From your coding agent, /cl-dev:handoff posts the /architect or /implement comment for you, on the right issue or pull request.

Follow a run and find its results

• Your comment gets an 👀 reaction when CodeLantern receives the command.
• A progress comment such as Running `/architect`... appears with a link to the GitHub Actions run.
• The work lands where you'd expect: the feature branch, the draft pull request, and the plan and session files under .codelantern/work-items/. After /implement, the pull request is marked ready for review, and the issue gets an "Implementation complete" comment pointing to it.
• A completion comment summarizes what the run did, with the run link and the command. For /implement posted on an issue, the "Implementation complete" comment takes its place.

When a run doesn't start or fails

• No reaction and no comment. CodeLantern didn't act on the comment. Check that it's a new comment that mentions @codelantern-ai, that you're an owner, member, or collaborator on the repository, that the CodeLantern GitHub App is installed on it, and that the repository has an active configuration in the portal.
• A comment says the issue is missing a label. The command's requirement in the table above isn't met. For example, /architect needs a spec'd issue. Run the earlier step, then try again.
• A comment says CodeLantern couldn't start the run. CodeLantern may not have access to the repository, or its integration may need reconnecting. Check the GitHub App installation and the repository's status in the portal. If it keeps happening, contact CodeLantern support and include the comment.
• A comment says the command failed. Open the linked workflow run in the repository's Actions tab. The failing step's log names the problem, for example Copilot not being allowed in GitHub Actions, or project dependencies that didn't install.
• An 👀 reaction, but no progress comment. Open the Actions tab and look for a CodeLantern Dispatch run. If there's none, make sure cl-dispatch.yml is on the default branch and that GitHub Actions is enabled for the repository. If the run failed early, its first failing step names the problem, such as the GitHub integration not being connected in the portal.