Troubleshooting kill9

Start with the visible symptom. Change one thing at a time, then repeat the exact action that failed. Keep the error text and the check you ran; both are more useful than a screenshot of a blank state.

Fast diagnosis

Installation

There is no Windows installer

Windows builds are coming soon. Public builds currently target macOS Apple Silicon, macOS Intel, and Linux x64.

The installer chose the wrong target

The installer prints its detected platform and architecture before downloading. Expected values are:

• macOS Apple Silicon: darwin/arm64
• macOS Intel: darwin/x64
• Linux Intel/AMD: linux/x64

If the printed value is wrong, stop the installer and use the matching direct download at kill9.ai/download.

The app will not open

Launch it once from a terminal so the error stays visible.

macOS:

open /Applications/kill9.app

Linux:

~/.local/bin/kill9.AppImage

Then check:

1. The installed path exists.
2. The platform and architecture match your machine.
3. No old kill9 process is still closing or updating.
4. Re-running the installer completes without an error.

Use Install kill9 for the exact files the installer creates.

Workspace setup

No repository is available

The project and local workspace are separate parts of setup. Select the project, then attach the local folder that contains its code.

Check that:

1. The folder still exists at the same path.
2. Your user account can read it.
3. The workspace lists the repository after selection.
4. The repository verification commands match the project.

Cortex does not become ready

Cortex is the workspace service kill9 uses to understand and operate on the attached codebase. If setup keeps waiting:

1. Confirm the attached folder is still accessible.
2. Close the workspace and reopen it once.
3. Read any visible startup error instead of repeatedly clicking Continue.
4. If the error names a project command, run that command in the repository and fix the repository-level failure first.

Verification commands are wrong

Do not approve commands just to finish onboarding. Update them to the commands a developer would actually run for install, build, test, lint, typecheck, start, or end-to-end verification.

A wrong command becomes bad evidence later when an agent claims a task is verified.

Models and providers

No model appears in the composer

Check in Settings → Models:

1. At least one provider is connected.
2. Its OAuth session or API key is still valid.
3. The provider account can use the selected model.
4. A default model is selected.
5. Your network can reach the provider.

Open a fresh session after changing the default model.

The provider rejects a request

Keep the provider's exact error. Common categories are invalid credentials, account access, model availability, rate limits, and network failure. kill9 cannot fix an account-level restriction; confirm it in the provider's own console.

Do not paste a full API key into chat or a bug report.

Responses are slow or stop partway through

Separate provider latency from a blocked kill9 workflow:

1. Check whether the agent is still marked working.
2. Look for a pending tool permission, question, or approval gate.
3. Open the specialist session to see the last completed action.
4. Try one smaller request in a fresh session with the same model.
5. Check the provider's status if both sessions stall.

Agent sessions

The answer is too broad

Narrow the observable result:

Do only the first safe step. Touch only the files required for that step, run the focused check, and show the evidence before continuing.

The agent wants to edit too much

Stop the run and restate the boundary:

The requested behavior is limited to [scope]. Do not refactor adjacent code. If another file is required, explain why before editing it.

The agent made an unsupported claim

Ask for evidence, not reassurance:

Which file, documentation page, test output, or tool result supports that claim? If none does, mark it as an inference.

A child agent stopped or disappeared

Open the parent orchestrator session first. It owns the job and should know whether the child completed, failed, was cancelled, or still needs input. Resume or redispatch from the parent so the workflow state stays connected.

A tool is waiting for permission

Read the command, target path, and stated reason. Approve only when they match the task. Reject it and narrow the request when the command is broader than necessary.

Workflows and review gates

A workflow will not move forward

Ask k9:

Name the blocked transition, the gate that stopped it, and the exact evidence still required. Do not bypass the gate.

Common blockers include:

• A required PRD or ADR is still draft or in review.
• Stories or measurable acceptance criteria are missing.
• The implementation check has not run or failed.
• A review has unresolved findings.
• The human approval for the next transition has not been given.

Fix the missing evidence. Do not force the state forward merely because the implementation looks finished.

A document says approved but the workflow disagrees

Treat that as a state mismatch, not permission to bypass the workflow. Capture:

• Document name and visible status.
• Initiative or story identifier.
• Transition you attempted.
• Gate error text.

Then report the mismatch so both surfaces can be reconciled.

Integrations

An expected source is missing

Available integrations include GitHub, Linear, Jira, Sentry, and Telegram. Slack, Datadog, and GitLab are not currently available integrations.

Connected source has no items

Check:

1. The connected account can see the expected organization or project.
2. The selected source points at the correct scope.
3. The item is not hidden by the current inbox filter.
4. Reconnecting the source completes without an authorization error.

Sentry does not connect

Confirm the configured Sentry organization and authorization token are correct. Rotate a token that may have been exposed, then reconnect with the replacement.

Secrets and private data

I pasted a secret into chat

Rotate the secret immediately. Remove it from shared logs, documents, tickets, or transcripts where possible. Assume a secret copied into an agent session may have reached the configured model provider.

Never include credentials in screenshots or public issue reports.

Report a problem

Include enough evidence for another person to reproduce the same state:

• Operating system and architecture.
• kill9 version and release channel.
• Workspace surface and action you attempted.
• Provider and model, without credentials.
• Agent or workflow involved.
• Exact error text.
• Expected result and actual result.
• Whether the failure repeats in a fresh session.
• A screenshot only when visual state matters.

Remove API keys, access tokens, private repository content, and personal data before sharing the report.