Technical Details

Problem Statement

When an agent framework provides a very large set of tools to the LLM, model performance tends to degrade. Not only does a large toolset take up a lot of tokens, but models—especially quantized ones—often start hallucinating tool parameters or even tool names.

Solution: Tool Families

Turbostar groups tools into "tool families", most of which are not enabled by default. The LLM is provided a tool call to activate a tool family, along with a list of available families including descriptions that inform the LLM when to activate a specific family.

To illustrate this concept better, below is a list of some available tool families in Turbostar. Plugins can also register their own tool families dynamically.

• git: All the tool calls to interact with the Git version control system.
• hexinspect & containers: Tools to natively analyze and hex-dump binary files, as well as peer into and extract components from complex container formats (PDF, tar, zip).
• image: Image processing tools (zoom, rotate, crop, format conversion, etc.).
• x86asm: Tools to assemble, disassemble, and analyze x86/x64 machine code.

In agent definition files (e.g., agent.md), we extend the agent specification with an option that specifies which tool families are enabled by default for that agent. For example, a coding agent will have the "git" family enabled by default, while an agent working on webpages may have the "image" tool family enabled, but not the Git family.

Backtraces & Interception

Native applications (C, C++, etc.) can crash for many reasons—from chasing a bad pointer to hitting an assert() or failing to handle an exception. Turbostar wraps test and application execution with a special LD_PRELOAD library (libturbocatch.so) that intercepts key signals and carefully writes a stack trace to a dedicated location.

The main Turbostar application uses this backtrace file to decode addresses (something that is not safe to do inside signal handlers) and turn them into an actionable report. Turbostar maintains an internal crash database so users and AI agents can review crash details at any time. For human editor users, backtrace entries within the project include a "go to source" option.

Human & Agent-Friendly Crash Reports

To ensure both the agent and the developer share the same high-quality context, crash reports are formatted exactly how a human reverse-engineer would expect to see them. They include signal information, fully resolved DWARF backtraces, and a Codemap summary mapping stack frames directly to function boundaries:

## Crash Report

### Info
Signal: 11
CrashAddress: 0x0 (read)
Type: SEGV_MAPERR
Executable: /home/arjan/git/turbotest9a/build/testcase
CrashCookie: run_1001

### Backtrace
| Frame | Address          | Function        | Location                                                                      |
|-------|------------------|-----------------|-------------------------------------------------------------------------------|
| 0     | `0x7f59d6d74ca9` | `__strcpy_avx2` | /build/reproducible-path/glibc-2.42/sysdeps/x86_64/multiarch/strcpy-avx2.S:80 |
| 1     | `0x5576dedcf168` | `foo(char*)`    | main.cpp:10:5                                                                 |
| 2     | `0x5576dedcf1ae` | `main`          | main.cpp:17:9                                                                 |

### Codemap Summary
| path       | Symbol | start_line | end_line | lines |
|------------|--------|------------|----------|-------|
| `main.cpp` | `foo`  | 5          | 11       | 7     |
| `main.cpp` | `main` | 12         | 18       | 7     |

### Coredump Debugging
A coredump is available for this crash. You can launch a GDB session to debug this coredump by calling the 'agent_debug_coredump' tool.

Steering the Agent (Least Friction Principle)

Many LLMs will try to guess the issue based on minimal logs, jumping to incorrect conclusions on complex bugs. Turbostar uses the Least Friction Principle: we inject the crash root cause directly into the execution tool output so the LLM has zero friction diagnosing it.

When an application crashes, the agent receives an immediate, structured notification explicitly telling it how to retrieve the coredump:

{
  "crash_notification": "\n\nCRASH DETECTED: Application crashed (Crash ID: 1028928).\nSummary: assertion fail at ../main.cpp:8 `c != NULL` in void foo(char*)()`\nPlease use 'crashdump_get_info' with crash_id '1028928' to investigate stack trace and details.",
  "is_alive": false,
  "status": "ended"
}

Generating Coredumps

Coredumps are the ultimate data source for analyzing crashes, containing a full memory snapshot of the application at the moment of failure. However, reliably generating a coredump file turns out to be a nightmare of Linux distribution-specific quirks. Systemd's coredumpctl? Not on Debian. Running ChromeOS? Forget it. Running inside a container? All bets are off.

Turbostar uses coredumpctl if available, but libturbocatch.so additionally triggers execution of gdb's gcore utility to produce a kernel-independent coredump file. While neither tool is individually perfect, this dual-attempt approach ensures coredumps are reliably generated for every crash.

Agent GDB Architecture

From the backtrace details, a one-click "GDB window for the coredump" option is available to human editor users, while a fully interactive gdb session is just one tool call away for AI agents.

Instead of forcing the LLM to run bash commands blindly, Turbostar acts as a mediator: the LLM sends commands (like info locals), and Turbostar pipes them through gdbserver to the application, parsing the output back cleanly to the LLM.

// Example GDB Tool Call Result:
frame 11
#11 0x0000560239369191 in foo (c=0x0) at ../main.cpp:8
8 assert(c != NULL);
(gdb) info locals
buffer = "\002V\000"
(gdb) info args
c = 0x0

An example crash dump provided to an AI agent can be viewed on GitHub.

Profiling Subsystem

Turbostar includes native basic performance profiling. While the Linux perf CLI tool is powerful, its output format is not editor-friendly. To provide basic profiling, Turbostar invokes the perf_event_open system call directly to collect a cycle-based profile.

Profile collection is subject to strict Linux security policies. To minimize required permissions, profiles are gathered using an LD_PRELOAD library (libturbocatch.so), scoping sampling strictly to the target process and its children.

Symbol resolution and data accumulation are handled by the main Turbostar application, producing per-line and per-function datasets. Hot lines are highlighted directly on the editor window frame, and the F7 hotkey allows quick navigation between hotspots in the code.

AI agents can request profile collection during normal app execution tool calls. Profiles are stored in an in-memory database, allowing agents to compare "before" and "after" runs and query function-level or source-file-level details.

Why Linux Perf is a Bad Fit for LLMs

The native integration described above is critical because the standard Linux perf CLI tool is not a natural fit for LLMs:

• Assembly vs Code Lines: perf operates primarily on assembly instructions. LLMs "think" in terms of high-level functions and source code lines.
• Messy Parsing: perf output is designed for humans and varies wildly by version.
• Massive Data: Raw performance profiling generates a massive amount of data. Feeding raw perf record logs into an LLM will instantly exhaust the context window.

The Turbostar Solution

Instead of raw logs, the agent receives condensed summaries (agent_get_profile_summary) showing only the top bottleneck functions. If the agent wants to drill down, it calls agent_get_profile_details to get exact line-by-line attribution of CPU samples directly mapped to the source code—costing only a few hundred tokens instead of millions.

Compiler Output

Compiling software can generate verbose output—for example, Meson emits over 1,000 lines when compiling Turbostar. Most of those lines (successful, warning-free build steps) offer no value to the LLM while consuming substantial context window tokens.

Turbostar parses standard output from common build systems like Meson and filters out noise lines. While this applies primarily to compiled languages, the reduction in context-consuming tokens is typically between 20x and 50x!

Test Suite Output

Similarly, test suite output follows standard formats. Turbostar filters out successful tests, presenting only test failures for the LLM to analyze.