Investigations & the agent

Work in Codepanion is organised into investigations: a chat thread where you ask a question and the agent works toward an answer. It streams its reply as it writes it, and uses tools as it goes:

search_codeSemantic (vector) search over your indexed source. It finds the relevant files and lines by meaning rather than by exact wording.
search_textExact keyword search over the same indexed source, file paths included. The right tool when the agent has an identifier, error message, or config key in hand and needs every place it appears verbatim.
describe_schemaReads your database's structure (tables, views, columns, types, keys and indexes) so a query is written against what actually exists rather than a guess at it.
query_databaseRuns a read-only query against your connected database and returns the rows.
read_codepanionPulls in the relevant .codepanion context file when it needs domain knowledge.
search_issuesLooks up existing issues in a connected issue tracker (see integrations).
search_logsSearches your connected log source by free text, level, and time range. The right tool when a code path or a query alone doesn't explain a failure. Offered only when a log source is configured.
get_log_contextPulls the log entries surrounding a moment in time: the "what else was happening then" view, optionally narrowed to a single distributed trace.
run_jsRuns a short JavaScript calculation in a sandbox in your browser, so arithmetic, date maths and aggregation over a result set are computed rather than guessed. See computing over results.
render_chartDraws a bar, line or headline-number chart in your browser from rows it already queried. A chart drawn from a query can be saved as a report. See charts and saved reports.
create_issueFiles an issue in a connected tracker. It writes to a system outside Codepanion, so it never runs until you approve it.
propose_changeTurns a fix the agent has worked out into a unified-diff patch, and, for a true one-liner on GitHub, a draft pull request. Also approval-gated.

You watch each step happen as it runs, and the findings cite the exact files and lines the agent read, so you can check the answer against the source.

The tools available on a turn depend on your configuration. Log tools appear after you configure a log source. Docs and issue-tracker tools appear after you connect the corresponding integration. The browser-based run_js and render_chart tools appear only on a live streamed turn.

Screenshot of An answer, with its working shown. The agent answers in plain English and shows every step it took to get there: the code it searched, the query it ran, and the rows that came back. — The agent answers in plain English and shows every step it took to get there: the code it searched, the query it ran, and the rows that came back.

Starting an investigation

New Investigation asks for one line: the symptom as the customer reported it. That line becomes the investigation's title, and the conversation itself starts empty, so your first message is the question you'd have asked a colleague.

Every investigation your team has opened is listed together, so a colleague can pick up a thread you started. The filters above the table narrow it to Open, Closed, or Mine.

Screenshot of The investigation list. Every investigation your team has opened, newest first. Filter to the open ones, the closed ones, or yours. — Every investigation your team has opened, newest first. Filter to the open ones, the closed ones, or yours.

Inside an investigation, the header carries the rest of the controls: the cost meter, Export, the environment picker that scopes the whole thread to one environment, the assignee, and Close.

Watching a turn run

A reply is streamed. The answer appears a few words at a time, and each tool step shows up in the thread the moment the agent starts it, so a turn that searches your code, reads a .codepanion note and then queries the database reads as a sequence of things happening. When the turn finishes, the live bubble is replaced by the saved conversation; what you watched and what is stored are the same thing.

Screenshot of The answer as it arrives. The reply builds while the agent works, so you can watch which file it opened and which query it ran instead of staring at a spinner. — The reply builds while the agent works, so you can watch which file it opened and which query it ran instead of staring at a spinner.

Two of the steps can stop and wait for you. An outbound write pauses for your approval, and run_js hands a calculation to the sandbox in your browser and waits for the result. Both resume the same turn once they're answered.

If the browser can't hold a stream open, the turn still completes. It arrives as a single reply at the end instead of live. Approvals need the live channel, so the agent's write tools are unavailable on a non-streamed turn. The agent will tell you that no action was taken.

Branching a conversation

Any message in an investigation can be forked into a new path. Branch From Here starts a fresh continuation from that message: it inherits the history up to that point, and the continuation you already had stays exactly where it was.

It's the "what if I'd asked it differently" button: explore an alternative line of reasoning without losing the thread you have. Where a message has more than one continuation, a Branch N of M switcher moves between them.

Screenshot of Two answers to the same question. Re-ask from any point in the thread and the first answer stays exactly where it was, so you can compare two lines of enquiry instead of losing one. — Re-ask from any point in the thread and the first answer stays exactly where it was, so you can compare two lines of enquiry instead of losing one.

Reading tool steps

Every tool call the agent makes is rendered as a short, plain-language step ("searched your code for refund handling," "ran a query against orders") so you can follow the reasoning without reading raw JSON.

Need the underlying detail? Each step has a Show Details disclosure that reveals the exact tool input and output.

Screenshot of Inside a tool step. Show Details opens the whole exchange: the structured query the agent asked for, the environment it ran against, the SQL that was compiled from it, and the rows that came back. — Show Details opens the whole exchange: the structured query the agent asked for, the environment it ran against, the SQL that was compiled from it, and the rows that came back.

What's inside depends on the tool: for the search tools it's the query the agent ran and the files that matched; for query_database it's the generated SQL and the rows that came back, set out in full under seeing what ran. There is no view of the agent's access that you don't have.

Tokens & cost

Each investigation shows a live cost meter in the chat header: the tokens used so far and the running estimated cost in dollars. The meter updates after every turn, so you can see what an investigation is costing while it runs rather than on next month's bill.

Screenshot of Investigation cost and export. The investigation header shows its running cost, pinned environment and owner. Export downloads the conversation as Markdown. — The investigation header shows its running cost, pinned environment and owner. Export downloads the conversation as Markdown.

Usage is metered per account. Account-wide spend is available from us on request while the in-app usage page is built.

Exporting an investigation

Export, in the investigation header, downloads the whole thread as a Markdown file, with the conversation, the tool steps, and the code citations included. It's the quickest way to drop a finding into an issue, a postmortem, or a Slack thread, or to hand a teammate the whole trail of how an answer was reached.

Known issues

Some context is true across every investigation: a flaky downstream service, a quirk in how a legacy table is populated, a workaround support already knows about. You can pin these as Known Issues for your tenant, and the agent factors them in automatically on every investigation.

It saves re-explaining the same caveat each time, and keeps the whole team's answers consistent with what you already know.

Screenshot of Context the agent always has. Record the quirks, gotchas and domain rules your team knows. The agent reads them at the start of every investigation. — Record the quirks, gotchas and domain rules your team knows. The agent reads them at the start of every investigation.

Each note is a short title plus the note itself: "Amounts are stored in cents", then the sentence that says a £12.50 charge is 1250. They apply to every investigation your team runs, and any of them can be removed when it stops being true. Keep them short and factual, because they're part of the agent's context on every investigation you run.

Context that matters to one investigation only goes in Investigation Notes instead: a collapsible panel at the top of the thread, pinned to that investigation, which the agent reads on every turn of it alongside the known issues your whole team shares. Same shape as a known issue, a short title and a note, and any of them can be removed once the investigation has moved past it.

Screenshot of Notes that belong to one investigation. Anything you learn while digging can be pinned to this investigation alone, and the agent reads it on every turn of this thread. — Anything you learn while digging can be pinned to this investigation alone, and the agent reads it on every turn of this thread.