Idea to Spec Local Agent

Local runner connector for idea_to_spec workflow jobs.

The connector runs on a developer machine, inside a project repository. It never opens inbound ports. It registers with idea_to_spec once, polls jobs over HTTPS, runs the selected local AI tool, and reports status back to the project workflow.

Install

npx @cyrnixlab/idea-local-agent --help

Connect a repository

Copy the one-time command from the project runner settings and run it from the repository root:

npx @cyrnixlab/idea-local-agent connect \
  --server https://idea.example.com \
  --token idea_setup_xxx \
  --repo . \
  --agent codex \
  --model gpt-5.2-codex \
  --reasoning xhigh \
  --start \
  --interval 10 \
  --concurrency 3

The setup token is short-lived and is not stored. After registration the local config stores only the runner token in .idea-to-spec/local-agent.json with 0600 permissions.

With --start, the command stays in the foreground and keeps polling idea_to_spec for queued workflow steps. Keep the terminal open while this runner should process jobs. --concurrency starts several polling worker loops in the same process. The backend still atomically claims every workflow step, so two workers cannot execute the same step.

To restore an existing runner from a new setup token, use the same options with reconnect:

npx @cyrnixlab/idea-local-agent reconnect \
  --server https://idea.example.com \
  --token idea_setup_xxx \
  --repo . \
  --agent codex \
  --start \
  --interval 10 \
  --concurrency 3

Run

npx @cyrnixlab/idea-local-agent start --repo . --interval 10 --concurrency 3

For a single claim/execute/report cycle:

npx @cyrnixlab/idea-local-agent run-once --repo .

To verify local configuration without starting the polling loop:

npx @cyrnixlab/idea-local-agent status --repo .

Agent modes

• codex: runs codex exec in the repository.
• claude: runs Claude Code in the repository.
• mock: returns deterministic markdown for smoke tests.

--model and --reasoning are optional local defaults. A workflow job can override reasoning through job.agentProfile.reasoning, job.input.step.agentProfile.reasoning, or the legacy job.input.reasoningEffort field.

Supported reasoning values:

• low
• medium
• high
• xhigh

The child process receives:

• IDEA_TO_SPEC_SERVER
• IDEA_TO_SPEC_WORKFLOW_RUN_ID
• IDEA_TO_SPEC_ANALYSIS_PROJECT_ID
• IDEA_TO_SPEC_STEP_RUN_ID
• IDEA_TO_SPEC_STEP_ID
• IDEA_TO_SPEC_STEP_TYPE
• IDEA_TO_SPEC_OUTPUT_ARTIFACT_TYPE
• IDEA_TO_SPEC_JOB_PROMPT_PATH
• IDEA_TO_SPEC_JOB_RESULT_PATH

Security model

• No inbound connection to the developer machine.
• No secrets are committed or shipped in this repository.
• The setup token is used only for /workflow-runners/register.
• The long-lived runner token is local to the repository checkout.
• .idea-to-spec/ should be ignored by Git.
• Revoke a runner from the project runner settings.

Publishing

The package is intended to be published under the npm scope @cyrnixlab:

npm test
npm run smoke
npm pack --dry-run
npm publish --access public

Before publishing, make sure the GitHub repository URL in package.json matches the public repository that hosts this code.