Last Signal: An Offline-First AI Agent Forensic CLI | Giving Ghosts a Voice After Failure

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine

What I Built

Last Signal 📡👻 is an offline-first terminal CLI for investigating failed AI-agent executions through evidence-grounded digital autopsies.

The Problem

Autonomous AI agents operate through dynamic execution loops: formulating plans, invoking tools, observing outputs, and retrying on errors. But when an agent fails, developers are typically left sifting through sprawling, noisy JSONL execution logs.

Common failure scenarios include:

• Looping on Broken Tools: Invoking the same failing tool repeatedly without adapting input parameters.
• Unproductive Retry Cycles: Burning token and retry budgets on non-transient infrastructure errors (e.g., connection refused, closed ports, invalid credentials).
• Silent Terminal Crashes: Encountering an unhandled tool exception immediately before termination, without leaving an explanation.

Traditional cloud observability platforms (APMs) may require sending sensitive internal trace logs, database queries, and private prompts to remote servers, creating privacy concerns and complications for air-gapped development workflows.

Theme Interpretation: "Ghost in the Machine"

In computing and philosophy, the "Ghost in the Machine" describes the elusive consciousness operating within physical hardware. When an autonomous AI agent crashes, its internal reasoning vanishes into the machine, leaving behind only cold execution footprints.

Last Signal treats every failed agent run as a digital ghost. Its final trace is its last signal.

It reconstructs the timeline of causality and conducts a digital autopsy through three core principles:

1. Deterministic Ground Truth First: Rule-based heuristics identify repeated tool errors, unproductive retry loops, and terminal crashes using verifiable evidence and exact event line numbers.

2. Local AI Interpretation: Connects exclusively to a locally running Ollama daemon (llama3.2) to synthesize natural-language hypotheses and debugging recommendations without transmitting trace data to external AI services.

3. 100% Offline Core & Fallback: If Ollama is unavailable or --no-ai is passed, the core detection engine and report generator remain fully operational.

Demo

Code

sahilsalunke42 / last-signal

Last Signal 📡👻

"Ghost in the Machine" — Offline-first digital autopsy CLI for investigating failed AI-agent executions.

---

1. The Problem

Autonomous AI agents operate as dynamic loops: formulating plans, calling model APIs, invoking local or remote tools, and attempting retries upon failure.

When an agent fails, developers are typically left sifting through sprawling, noisy JSONL execution logs. Agents often fail in predictable yet subtle ways:

• Looping on Broken Tools: Invoking the same failing tool repeatedly without adapting parameters.
• Unproductive Retry Cycles: Exhausting token and retry budgets on non-transient infrastructure errors (e.g., connection refused, missing credentials).
• Silent Terminal Crashes: Encountering an unhandled tool exception immediately before dying without recording an explicit recovery path.

Traditional cloud observability platforms require sending sensitive internal trace logs to remote servers, violating privacy and local development workflows.

---

2. The Solution: Last Signal

Last Signal is an offline-first terminal CLI for investigating failed AI agents. Built around…

View on GitHub

Code

• Language: Python 3.10+
• License: MIT
• Key Libraries: Typer (CLI), Rich (forensic terminal UI), Pytest (68 automated unit and integration tests).
• Local AI: Ollama HTTP REST API (localhost:11434).

Quick Install

pip install git+https://github.com/sahilsalunke42/last-signal.git

How I Built It

Last Signal was designed with an offline-first, dual-engine forensic architecture that separates deterministic failure detection from local AI interpretation.

Architecture Overview

flowchart TD
    subgraph Ingestion["1. Streaming Ingestion"]
        A["Agent Execution / JSONL Trace"] --> B["trace_reader.py"]
        B --> C["models.py: TraceEvent"]
    end

    subgraph Detection["2. Deterministic Ground Truth"]
        C --> D["FailureDetector"]
        D --> E["RULE-REPEATED-TOOL-FAILURE"]
        D --> F["RULE-UNPRODUCTIVE-RETRY-LOOP"]
        D --> G["RULE-TERMINAL-TOOL-FAILURE"]
        D --> H["RULE-UNRECOVERED-EXECUTION-FAILURE"]
        E --> I["AnalysisReport"]
        F --> I
        G --> I
        H --> I
    end

    subgraph LocalAI["3. Local AI Interpretation"]
        I --> J["OllamaClient"]
        K[("Local Ollama Daemon<br/>localhost:11434")] <--> J
        J --> L["AIDiagnosis"]
    end

    subgraph Output["4. Forensic Presentation"]
        I --> M["Rich Terminal UI"]
        L --> M
        I --> N["Markdown Autopsy Export"]
        L --> N
    end

1. Process Supervision (lastsignal run)

Last Signal executes target commands using Python's subprocess.Popen without shell invocation (shell=False).

The process supervisor:

• Captures stdout and stderr using dedicated non-blocking background threads.
• Extracts structured event tags such as [tool_call], [tool_result], and [retry].
• Captures unhandled Python stack traces.
• Generates structured JSONL execution traces.
• Archives execution traces inside .lastsignal/traces/.

2. Deterministic Failure Detection Engine

Before consulting any AI model, Last Signal applies four deterministic heuristics to identify behavioral failure patterns.

Detection Rule	Purpose
RULE-REPEATED-TOOL-FAILURE	Detects when a single tool records two or more distinct operational failures.
RULE-UNPRODUCTIVE-RETRY-LOOP	Identifies operations entering retry cycles without any subsequent recorded success.
RULE-TERMINAL-TOOL-FAILURE	Pinpoints the proximate tool failure immediately preceding session termination.
RULE-UNRECOVERED-EXECUTION-FAILURE	Identifies unhandled process exit codes where no recovery occurred.

Every finding explicitly differentiates between:

• Explicit Evidence: Directly supported by logged error messages or execution statuses.
• Inferred Evidence: Derived from temporal event ordering and execution context.

This ensures that the forensic engine distinguishes observed failures from conclusions inferred through execution history.

3. Local AI Synthesis via Ollama

For narrative post-mortem generation, Last Signal communicates with a locally running open-weight model through Ollama's HTTP REST API.

Supported models include:

• llama3.2:latest
• qwen2.5

Local API: http://localhost:11434

Two important design decisions make this integration reliable:

• Prompt Grounding: The model receives verified deterministic findings as context, restricting its diagnosis to observed evidence rather than inventing unobserved tools or actions.
• Graceful Degradation: If Ollama is unavailable or the user passes --no-ai, Last Signal logs a notice and delivers the complete deterministic forensic report without failing.

4. Forensic Visual Design System

Last Signal features a dark, respectful Digital Afterlife aesthetic inspired by Día de los Muertos remembrance.

The terminal interface uses a purpose-driven color system:

Color	Hex Code	Purpose
Bone White	#E8E0D2	Primary forensic text
Marigold Amber	#E8A23A	Retries, warnings, and evidence badges
Crimson	#D64B55	Fatal crashes and critical findings
Spectral Teal	#65B8A5	Verified operational successes
Mourning Violet	#A78BFA	Local AI hypotheses

The visual language reinforces the forensic workflow by distinguishing verified evidence, operational warnings, critical failures, and AI-generated interpretations.

Why Does Open Innovation Matter?

AI-agent execution traces are among the most sensitive data streams in software engineering. They can contain internal system paths, proprietary prompt templates, user database queries, API credentials, and internal reasoning traces.

Traditional cloud-based observability platforms often require developers to transmit execution logs to third-party infrastructure, introducing additional privacy and data-sovereignty concerns.

Open innovation makes local sovereignty possible.

1. Zero Data Leakage

By combining open-source detection algorithms with open-weight models through Ollama, Last Signal eliminates the need to transmit execution traces to external AI services.

All forensic analysis and local inference happen on the developer's machine. This makes the architecture suitable for air-gapped environments, secure networks, and offline workflows.

2. Transparent, Verifiable Rules

When diagnosing why an agent broke in production, "AI said so" is insufficient.

Last Signal exposes its deterministic detection engine, including its heuristics, pattern-matching logic, and temporal analysis rules. Developers can inspect exactly how failures are identified and which execution events support each finding.

No black-box diagnosis. No blind trust.

3. Freedom from API Tollbooths

Developers debugging why their agents exhausted API credits shouldn't have to spend additional API credits just to diagnose the failure.

By using locally hosted open-weight models, Last Signal removes mandatory external AI API dependencies and recurring inference costs from its forensic workflow.

My Agent Session

Last Signal was built and refined with the assistance of agentic pair-programming sessions. The development process involved iterative design, implementation, testing, and refinement across several core components.

Key development activities included:

• Streaming Ingestion & Process Supervision: Architecting the streaming parser and unbuffered subprocess supervisor to capture agent execution events reliably.
• Deterministic Failure Detection: Designing four behavioral failure heuristics and validating edge cases against a suite of 68 automated tests.
• Terminal UI Engineering: Refining terminal color contracts, Unicode-to-ASCII fallback borders, and the overall forensic presentation.
• Report Security: Implementing Markdown sanitization to protect generated reports against injection attacks.

These sessions helped turn the initial concept into a functional, tested, and independently usable forensic CLI.

The Spirit of It

There is a distinct, eerie feeling when an autonomous agent you've been working on runs for several minutes in complete silence, only to abruptly terminate with a non-zero exit code. It feels like watching a ghost disappear from the terminal, leaving behind nothing but questions about what happened in its final moments.

The defining moment of building Last Signal came while testing its process supervisor against a simulated research agent trapped in an infinite retry loop because its database was unreachable.

Watching the terminal intercept the fatal crash, reconstruct the agent's final execution steps, identify the underlying failure patterns, and give that digital ghost a voice through an evidence-grounded diagnosis was the moment the idea truly came alive.

What started as a debugging problem became something more meaningful: a way to preserve the final signals of an otherwise unexplained execution.

Every failed agent leaves a trace. Last Signal ensures those signals are never lost.

Prize Categories

• Primary: Hacktoberfest Open-Source AI Challenge – Week 4: Ghost in the Machine