Skip to Content

Troubleshooting production issues with a read-only AI chat

Investigate a problem with a read-only debugging chat that can read your code, logs and database, and turn its diagnosis into a fix task.

When something is broken and you do not know why, start with an investigation instead of a fix. A troubleshoot session is a read-only debugging chat: the agent looks at the code and, if you allow it, at a running system - logs, a read-only database, allowlisted commands. It can never change anything. When it has found the cause, you turn the diagnosis into a normal fix task.

Start an investigation

Two ways:

  • Create a Troubleshoot task. In the full task form, choose the type Troubleshoot (see Tasks). Such a task has an Investigation tab instead of a spec. Open it.
  • From any task. Open the task's Troubleshoot tab.

Then:

  1. Under Start an investigation, choose an Environment: Code only, no live environment, or one of the project's linked environments. You see what the session will be able to do.
  2. Click Start investigation.
  3. Describe what is going wrong in Ask what is going wrong… and click Send.

Follow the investigation

The agent works step by step and shows everything it does: each Read logs, Query database (with the SQL) and Run command can be expanded to see exactly what was run and what came back. A request outside what is allowed is shown as refused.

While it works you see Thinking… or Investigating…. Ask follow-up questions, share what you know, or point it in a direction - it is a conversation.

Diagnose and fix

  1. When you think enough is known, click Diagnose. The agent concludes with a root-cause Diagnosis.
  2. Below it you are asked A diagnosis is ready. Turn it into a fix task? Click Create fix task.
  3. Click Open it to go to the new task. It follows the normal flow: spec, approval, run and pull request - see The spec (TSD) and approval.

A ready diagnosis also appears in the Inbox, with Create fix task right there.

Without an environment, a session can only read the code. To let it look at a running system, link an environment to the project. This requires being an organization admin or the project's owner.

  1. Open the project and go to Settings → Environments.
  2. Click Add environment and give it a Name, an Environment (for example production) and a Description of what runs there and anything the agent should know.
  3. Turn on only the capabilities you want to allow:
    • Code access - clone the project's repositories into the session's sandbox so the agent can read and search them.
    • Logs / observability - read logs from an HTTP endpoint, Grafana Loki, Sentry or GitHub Actions.
    • Read-only database - run bounded SELECT queries. Use a database role that can only read; CodeLynq also refuses anything other than SELECT, but the role's permissions are the guarantee that matters. You can limit the rows, the time per query and the tables it may see.
    • Shell commands (allowlist) - run only commands that start with a prefix you list, for example docker logs. Shell operators are refused, and an empty list means nothing may run.
  4. Save. The environment card shows its capabilities, and warns when one is switched on but incomplete.

Each capability is separate, so you can allow only logs on production and more on staging. Untick Active to stop sessions from using an environment without deleting it.

Good to know

  • Everything is read-only. A session cannot write to your database, change files or deploy.
  • The agent shows every query and command, so you can check exactly what it looked at.
  • Troubleshooting from your phone is not available; use the web app.
  • Also see Alerts: incoming monitoring alerts can open bug tasks automatically.

Test it on a task from your own backlog

Send us one real task. We run CodeLynq on your repository and you review the pull request. Free, within 5 working days of approving the spec.