Skip to main content

Workflows

Version: 1.0 | Last updated: 2026-07-09

Bluebox fits into your development cycle in two ways: reactively, when something has gone wrong, and proactively, when you want to understand your system before making changes. In both cases, you can hand what Bluebox finds directly to your coding agent.

Investigate a finding​

When Bluebox detects a problem, it appears on the Overview page. To investigate:

  1. Select Investigate on the finding's row.
  2. Bluebox traces the problem through your service topology, forms hypotheses, and assembles evidence from your live telemetry. It streams progress as it goes.
  3. When it finishes, Bluebox creates a GitHub issue with root cause, evidence, and a recommended fix attached.

The whole cycle — from finding to a GitHub issue with a proposed fix — typically takes two to ten minutes.

You can also start an investigation without a finding: open the Investigations page from the sidebar, describe the problem you want to look into, and Bluebox works from there.

Query production before you build​

You don't have to wait for something to break. Before writing code for a new feature, refactoring a hot path, or deciding where to focus effort, ask Bluebox what your production system actually looks like:

bluebox ask "which endpoints in the payments service have the highest p99 latency"
bluebox ask "what are the most common errors in the checkout flow over the last 7 days"
bluebox ask "is the orders service behaving normally compared to last week"

The answers draw from your live telemetry — real traffic patterns, real error rates, real service dependencies. Common uses:

  • Identify bottlenecks before deciding what to optimize, rather than guessing from code structure.
  • Check service health before touching a dependency, especially after a recent deploy.
  • Understand traffic shape before designing a new endpoint or changing a high-traffic data path.
  • Catch regressions early by querying a service right after a deploy, without waiting for an alert to fire.

Paste the output into your coding agent prompt. The agent starts from production reality, not a reconstruction inferred from comments and local file structure.

Use Bluebox in a coding agent session​

When you run bluebox setup, Bluebox installs a production-query skill into any supported coding agents it detects. After that, your coding agent can call bluebox ask on its own when it needs production context — you don't have to prompt it manually.

You can also pass context explicitly. Give the agent a bluebox ask response, an investigation result, or a GitHub issue and ask it to act:

Here is the output of `bluebox ask "top 5 slowest endpoints in the API service"`:
<paste output here>

Identify the highest-impact change we can make to improve p99 latency and open a PR.

The agent reads the production data alongside the code and writes a change grounded in what actually runs in your system.

For setup details — skill installation, CLI tokens, and connecting from Kiro or other agents — see Connections.

Turn an investigation into a pull request​

When an investigation finishes, its GitHub issue contains everything your coding agent needs to write a fix:

  • Root cause and the causal evidence chain
  • Affected services and endpoints
  • A recommended fix with specific guidance

To turn the issue into a PR, give it to your coding agent:

Implement the fix described in this GitHub issue: <paste issue URL or full issue body>

The agent locates the relevant code, implements the fix, and opens a PR. You review it before it merges — Bluebox and the agent propose; you decide.

If the recommended fix needs more context — for example, the investigation found a slow query but didn't pinpoint the call site — ask Bluebox from inside the coding agent session:

bluebox ask "which code paths call the orders endpoint most often"

Then pass that answer to the agent alongside the issue.

Next steps​

  • Core Concepts — findings, investigations, chat, and the CLI.
  • CLI Reference — every bluebox command and flag.
  • Connections — connect Bluebox to AWS DevOps Agent, Kiro, and other integrations.
  • FAQ — common questions and quick fixes.