# Debug a live application with an agent

When a local app is failing, the fastest useful agent is often the one that can see both the code and the running process. Solo lets a lead agent inspect command status and output, discover local service ports, open a separate diagnostic terminal, and turn a live symptom into a reproducible test.

The goal is not to ask an agent to guess at a stack trace. The goal is to move from symptom, to evidence, to a failing proof, to a verified fix.

## Give the agent the symptom and the process

Start with what you observed and point to the relevant Solo process. Include when it happens, what you expected, and whether restarting or changing process state is allowed.

```text
Investigate this as a live failure before editing code. Inspect the named Solo
process, its status, recent rendered output, detected ports, and relevant resource
signals. Reproduce the symptom if it is safe. Separate observed facts from your
hypotheses, identify the most likely root cause, and propose a failing regression
test. Only make a small fix after the evidence and test agree. Preserve unrelated
changes and do not restart processes unless the reproduction requires it.
```

You can give the agent a process name, process ID, or copied Solo process link. A precise target keeps it from scanning every terminal in the project.

## Build an evidence trail

Ask the agent to work from the outside in:

1. Read the process status and recent rendered output.
2. Search the output for the first error, repeated lifecycle event, or unexpected transition.
3. Check discovered ports and readiness when the problem involves a local service.
4. Use [Activity monitor](../activity/activity-monitor.md) when CPU, memory, subprocesses, or port ownership are part of the symptom.
5. Correlate the runtime evidence with the smallest relevant area of code.

[Output MCP tools](../mcp-tools/output.md) let the agent inspect Solo's saved terminal output directly. Rendered output is the normal starting point. Retained output can reveal text hidden by terminal rendering, but it is decoded and stripped of common terminal control sequences; it is not a byte-for-byte protocol capture.

If exact bytes matter—for example, when debugging terminal input, an escape sequence, or a binary protocol—ask the agent to [spawn a terminal](../mcp-tools/agent-terminal.md) and run the project's existing capture or diagnostic command there. Keep that terminal separate from the process being investigated so the evidence remains easy to compare.

## Reproduce before restarting

A restart can make a local problem disappear without explaining it. Ask the agent to preserve the useful output and write down the reproduction before changing process state.

Restart when the reproduction specifically requires a clean boot, a changed configuration, or a rebuilt service. Solo MCP can start or restart an existing trusted command, but [command trust](../commands/trust-security.md) still applies. For a service that needs time to bind a port, use Solo's [service readiness tools](../mcp-tools/services.md) instead of guessing how long startup takes.

For a UI problem, the agent can also inspect the detected local URL with whatever browser or screenshot tool you have configured. Ask it to capture the state before and after the fix, and to keep the same viewport and reproduction steps so the comparison means something.

## Turn the theory into a red test

Once the agent has a likely cause, ask for a test or other deterministic check that fails for the observed behavior. The test should exercise the user-visible failure or the state transition that caused it, not merely assert the new implementation.

Good red tests often cover:

- The exact input or lifecycle sequence from the logs.
- A repeated event that should be idempotent.
- A restart, reconnect, or retry boundary.
- An error path that previously left stale state behind.
- The smallest integration boundary where the failure becomes observable.

Sometimes the live symptom cannot be reproduced safely in a normal test suite. In that case, ask the agent to define a repeatable diagnostic command and explain why a conventional test is not credible. Do not accept “it seems fixed” as the only check.

## Drive the proof green

After the red test demonstrates the failure, authorize the smallest fix. Run the focused test first, then repeat the original live reproduction against the same Solo command.

The code test and live check answer different questions:

- The test proves the behavior is protected from regression.
- The live check proves the test models the failure you actually saw.

If the fix changes startup or runtime behavior, inspect process output again after the change. Confirm that the original error or churn is gone and that a new failure has not replaced it.

## Get an independent root-cause review

For a costly or subtle bug, spawn one read-only reviewer after the diagnosis and red-test plan are concrete. Ask it to confirm or deny the causal chain, inspect the test for blind spots, and cite evidence. Do not tell it that it must agree.

The lead should validate the review against the current code and runtime evidence. If the reviewer finds a real gap, update the test or fix and re-run the original reproduction. A second review is useful when it checks a specific corrected claim; repeated generic approval requests are not.

## Preserve the useful result

Before cleaning up, have the lead record:

- The symptom and exact reproduction.
- The process and output evidence used.
- The accepted root cause and rejected alternatives.
- The regression test and live verification result.
- Any unrelated failure or remaining risk.

Use a [scratchpad](../scratchpads/using-scratchpads.md) for a long investigation and a todo comment for the final task-specific handoff. Then close diagnostic terminals and reviewers that are no longer needed. The next time the symptom appears, you should be able to start from the evidence instead of reconstructing the whole investigation from chat history.

---

Are you a human? Read this doc on the web: https://soloterm.com/docs/workflows/debug-live-application