Let Copilot Explain Itself With Chronicle and Troubleshoot

In an earlier post, you learned that agent logs are the only reliable record of what your AI coding agent actually did. Under the covers, the Agent Debug views are supported by a very large .jsonl log file that captures the details from the session. Reading that log by hand, however, gets tedious fast. A single session can produce thousands of events, and a busy afternoon can produce dozens of sessions. While the log views are great for focused troubleshooting, sometimes you need the speed and reasoning of an agent to help you find issues in your agentic code.

That’s exactly the problem two built-in Copilot skills solve. Instead of you reading the logs, the agent reads them for you.

Two skills, two questions

There are two skills provided by Copilot for working with your agent logs:

• /troubleshoot

  Answers “what happened in this session, and why?” It reads the raw JSON Lines (JSONL) event log that the harness writes to disk for a single conversation, including the logs for any subagents that were spawned. This is currently only available in VS Code (for Copilot CLI, you can use /session info to find the path to the log and ask Copilot to review it directly)

• /chronicle

  Answers “what have I been doing, and how could I do it better?” It queries across your session history rather than focusing on a single specific event file. This can also help to find sessions that have become hidden or identify where specific steps were taken by looking across the earlier sessions.

In short, troubleshoot is a microscope and chronicle is a map. You reach for the microscope when one run went sideways, and for the map when you want to spot a habit or refine a behavior.

Turning on the log files

Neither skill can help you if nothing is being written to disk. In Visual Studio Code, enable github.copilot.chat.agentDebugLog.fileLogging.enabled and then reload the window. That setting is what tells the harness to write events – tool calls, model requests, token usage, and errors – into JSONL files instead of only keeping them in memory. You may also want to enable chat.agentHost.agentDebugLog.enabled. These must be done before starting the session. After setting these values, I recommend reloading the window (or, better yet, stopping and restarting Visual Studio Code). The chronicle command requires the github.copilot.chat.localIndex.enabled setting to be true so that it can search a local index.

For Copilot CLI, quite a bit is directly written to the session event logs. You can find that path by using /session info. You can also use the OpenTelemetry environment variables to generate enriched log files to a specific location. Using OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT enables a deeper capture of message content into the logs. Specifying COPILOT_OTEL_FILE_EXPORTER_PATH enables directly writing the OpenTelemetry logs to the specified location.

Running troubleshoot

Once logging is on in VS Code, you can invoke the skill directly from the chat view with a slash command and a plain question:

/troubleshoot why did you skip my release-notes skill?
/troubleshoot which paths did you search when loading customizations?
/troubleshoot how many tokens did this session use, and where did they go?

By default, the skill looks at the session you’re currently in. If you want to examine a different session, add #session to your prompt and pick the session from the list.

Under the covers, this is just a skill, and reading it provides a lot of insights about what it makes available. A key part of the skill is this section, which documents the files used by VS Code to track session data:

- Target session log directory/directories for analysis: `{{VSCODE_TARGET_SESSION_LOG}}`

Use direct debug log files written by Copilot Chat:

debug-logs/<sessionId>/
  main.jsonl                              — always start here; primary conversation log
  models.json                             — (optional) snapshot of available models at session start
  system_prompt_0.json                    — (optional) full system prompt sent to the model (untruncated)
  system_prompt_1.json                    — (optional) written when the model changes mid-session
  tools_0.json                            — (optional) tool definitions sent to the model
  tools_1.json                            — (optional) written when the model changes mid-session
  runSubagent-<agentName>-<uuid>.jsonl    — (optional) subagent's tool calls & LLM requests
  searchSubagent-<uuid>.jsonl             — (optional) search subagent work
  title-<uuid>.jsonl                      — (optional, UI-only) title generation
  categorization-<uuid>.jsonl             — (optional, UI-only) prompt categorization
  summarize-<uuid>.jsonl                  — (optional, UI-only) conversation summarization

The system prompt has an instruction to always treat {{VSCODE_TARGET_SESSION_LOG}} as a specific location, and it provides that path. This is a variation of the same trick I previously discussed for skills. Since the path is predefined by a mention in the system prompt, the model can use that to find the remaining files without any guesswork.

Stepping back with chronicle

Some questions aren’t about one session at all. “Which repository am I burning the most tokens on?” and “What did I actually finish this week?” need history, not depth. When you need these kinds of answers, that’s where chronicle shines. This skill is also available in both VS Code and Copilot, meaning you can use it from wherever you work. Rather than parsing event files, it queries a local index of your session history built from your past conversations. The chronicle skill has several subcommands:

1. standup summarizes recent work as a status update, grouped by what’s done and what’s still in flight.
2. tips and cost-tips look at your prompting and token patterns and suggest changes.
3. search finds past sessions by keyword when you remember solving something but not where.
4. improve proposes concrete additions to your repository instructions based on what you keep repeating.
5. reindex rebuilds the index when the history and the store drift apart.
6. skills create, skills review, and skills status are available in Copilot CLI for helping you to convert a session into a repeatable skill.

If you’re wanting to refine the AI behaviors based on how AI is actually performing in your sessions, the improve subcommand is the tool to start with. It analyzes your sessions and recommends changes to your repository instructions. Of course, all of these tools can be used to help refine the effectiveness of your AI interactions.

Chronicle works by using a SQLite-based index to enable it to store and query your session history efficiently. This allows it to more rapidly identify relevant information. Unlike VS Code, it has a /session info command that gives you details about the current session and files natively. It also has tools for reading and writing that index, which give it an effective way to analyze the sessions.

What the raw log actually contains

Stepping back for just a moment, it’s important to realize these are just skills or prompts – something you could write yourself. They tell the AI tools how to access and read structured records of every event in your sessions. These are captured for analysis and troubleshooting, but they also provide a way to rewind the events or fork the session history for experimentation.

Under the covers, the primary event data is persisted into a jsonl file. It is in JSON lines format, with each object in chronological order, separated by a newline. Every line is one event with a consistent set of fields: a timestamp, a type, an identifier, a parent span identifier. After that, the fields depend on the event type. Because each event carries a parent, the flat file is really a tree. A user message leads to a model request, which leads to a response, which leads to tool calls, which lead to the next request. Tool call events record the exact arguments sent and the results returned. Other events provide the details of the model requests, responses, and reasoning. This is what lets the agent answer “why didn’t my skill load?” with actual details instead of guesses.

The clever part: selective access

Here’s the design detail I find genuinely interesting, and it’s an architectural decision you might borrow for your own purposes.

Those log files do not live in your workspace. They’re written to a separate storage directory, well outside any folder the agent normally works in. That placement is deliberate. If the logs lived inside your repository, every workspace search could sweep them up. A single grep for a function name would drag hundreds of lines of serialized prompts, tool payloads, and past reasoning into the model’s context. Your logs would become your content, your context window would fill with noise, and you’d pay for the privilege on every request.

Keeping them outside the workspace makes them invisible by default. In addition, many of the activities in this environment may use tools to limit how the model interacts, helping to hide the presence. Since workspace search tools restrict access to the local workspace, it helps these files to remain invisible until the agent explicitly decides to open them for inspection.

The logs themselves are just files – files the agent can open and read line by line at your command. The skill’s prescribed workflow reflects that discipline: locate the directory, triage from the terminal with something like a filter for error statuses or long-running spans, and only then read the specific lines that matter.

That’s a meaningful distinction. The agent isn’t remembering what it did. It has no privileged introspection and no special self-awareness. It is reading a record of its own behavior, as evidence, the same way it would read any other file you handed it. Everything it tells you is grounded in something it can point to, which is exactly what you want from a debugging tool.

Making it a habit

You don’t need to read logs after every request. You do need to read them when something surprises you. The next time an agent says it’s done and the result doesn’t match what you asked for, resist the urge to simply re-prompt and hope for a better roll. Ask what happened and why, then fix the instruction, skill, or hook that led it astray. A sharpened skill or clarified instruction improves every future session, not just the current one. That’s the real payoff of letting the agent read its own logs: you stop debugging conversations and start debugging your approach.