PawSift 🐾 for Android Logcat

PawSift bridges Android Logcat to LLMs in a token-efficient way

PawSiftis a high-performance Model Context Protocol (MCP) server that bridges Android Logcat to LLMs. It provides a token-efficient, session-aware interface for real-time log analysis, using a polling-based SQLite ingestor to sift through raw output and surface only what matters.

- High-Throughput Processing: Regex-free manual string parser and hash-based dedup (usinghash/maphash) for hot-path log processing at 5,000+ logs/sec.
- Zero-Touch Session Tracking: Automatically detects app restarts viaActivityManagerand rotates sessions.
- Token Efficient: Pre-aggregates errors, folds repetitive consecutive logs, and usesHierarchical Mappingto group identical messages under sub-headers.
- Surgical Querying: Filter logs by level, tag, and search terms with strict line limits to protect the context window.
- Tag Discovery: Quickly list all active tags in the current session.
- Contextual Windows: Fetch logs surrounding a specific event for precise debugging.
- Global Search: Search the entire log history across all sessions with a single command.
- Status Dashboard: A specialized heartbeat tool to monitor watcher health, session IDs, and log backlog.
- Automatic Retention Policy: Enforces max log limits (default 10k logs, 3 sessions) with continuous cleanup during polling—prevents unbounded database growth.
- Configurable Cleanup: Adjust retention limits on-the-fly viaset_retention_policy()without restarting.
- WAL Mode SQLite: Write-Ahead Logging for concurrent read/write access withoutdatabase is lockederrors.
- Optimized Queries: Database indexes on tag, message, timestamp, and composite filters for fast lookups even with large log volumes.
- Maintenance: Built-in tools to clear both local and device log buffers.
- Go-Based: Fast, single-binary distribution with no CGO dependencies.

curl -fsSL https://raw.githubusercontent.com/dolphprefect/pawsift-mcp/main/install.sh | sh

irm https://raw.githubusercontent.com/dolphprefect/pawsift-mcp/main/install.ps1 | iex

Downloads the right binary for your OS and architecture, installs it to~/.local/bin/pawsift(or%USERPROFILE%\.local\bin\pawsift.exeon Windows), andautomatically registersthe server in your Gemini CLI and Claude Code (CLI) configuration files.

Supports: Linux amd64/arm64, macOS amd64/arm64, Windows amd64.

Builds from source and does the same install + registration as above.

Android logs are extremely verbose. A single app launch can produce thousands of lines, most of them repetitive noise. Feeding raw logcat into an LLM context is wasteful and often hits limits. PawSift addresses this at two levels.

Whenfold=true(the default inpawsift_query_logsandpawsift_search_logs), consecutive identical log messages are collapsed into a single entry annotated with a count and time range:

- [1042-1089] D 09:14.201 - 09:14.812 Choreographer: Skipped 48 frames (48x)

Without folding, that same stretch would emit 48 separate lines. A busy app with repeated WiFi probes, sensor polling, or animation callbacks can compress 200+ raw lines down to a handful of folded entries — a 10–50× reduction in tokens for those spans.

Beyond folding, results are structured usingHierarchical Mapping: logs are grouped first by tag and PID (### Tag (PID)), then by unique message (#### Message), with individual occurrences listed underneath. This means the LLM receives a structured summary rather than a flat stream:

### MyApp (12345) #### Failed to load resource - [301] E 09:15.001 - [318] E 09:15.430 ### NetworkManager (987) #### Socket timeout - [412] W 09:15.102

Repeated messages from the same source appear once as a header with their occurrences listed below, rather than duplicating the message text on every line.

Every log entry carries a stable[ID]. The summary tools (pawsift_get_error_summary,pawsift_get_tag_summary) return only counts and IDs — not the full log body. Once you have an ID of interest,pawsift_get_log_contextfetches just the surrounding window. This two-step pattern (summarise → zoom) avoids loading the full log history into context entirely.

PawSiftprovides an intelligent abstraction layer over raw Android logs, optimized for AI-assisted debugging. Follow this workflow for the best results:

Before you start testing, tellPawSiftwhich app you are focusing on:

User to LLM:"Set the target package tocom.your.app.packageand watch for logs."LLM Action:Callspawsift_set_target_package(package="com.your.app.package").

Orient yourself before starting a deep dive:

LLM Action:Callspawsift_get_status().Output:Shows if the watcher is active, the connected device serial, and the current log count.

Run your app on your device or emulator.PawSiftwill automatically detect the "Process Started" event and start a fresh session.

4. Identify the Crash (The "Bird's Eye View")

If the app crashes or behaves unexpectedly, start with a high-level summary to save tokens:

User to LLM:"What just happened? Any crashes?"LLM Action:Callspawsift_get_error_summary().Output:Returns unique error signatures, counts, and their latest[ID].

5. Investigate the Logs (Surgical Follow-up)

Don't query all logs. Use the[ID]from the summary to jump straight to the relevant context:

LLM Action:Callspawsift_get_log_context(log_id=1234, lines=20).Output:Returns 20 lines leading up to and following the crash, giving you visibility into state changes, network responses, or UI events.

- If you see too much system noise (e.g.,WifiHAL,AOC), tell the LLM:"Ignore system tags and focus on my app logs."
- Usepawsift_search_logs(query="FATAL EXCEPTION")to find specific events across the entire history if the current session summary is too broad.

PawSiftautomatically manages database growth with a configurable retention policy. By default:

- Max 10,000 logsare kept across all sessions
- Last 3 sessionsare retained; older ones are deleted
- Cleanup runs every 30 secondsduring polling to enforce limits

Usepawsift_set_retention_policy()to tune limits without restarting:

pawsift_set_retention_policy(max_logs=5000, max_sessions=2, cleanup_interval=15)

- Long debugging session: Reduce limits (5k logs, 2 sessions, 15s cleanup) to keep the database lean
- Quick reproduction: Increase limits (50k logs, 5 sessions, 60s cleanup) if you need more historical context
- Tight constraints: Minimal mode (1k logs, 1 session, 10s cleanup) for resource-constrained environments

After each cleanup cycle, disk space is reclaimed viaVACUUM.

PawSifthas comprehensive test coverage including unit tests, edge case parsing, concurrency stress tests, and data race detection.

make test # Standard test suite make test-race # With Go race detector (recommended before releases)

19 test functions across 6 files (21 top-level functions including subtests), all passing cleanly under-race.

All tests are verified withgo test -raceto guarantee no data races in the streaming pipeline, dedup map, and concurrent DB access patterns.

make deployhandles this automatically for Gemini CLI and Claude Code (CLI). For manual setup or other clients, use the following:

{ "mcpServers": { "pawsift": { "command": "/home/YOUR_USER/.local/bin/pawsift" } } }

- Binary Location:build/pawsift
- Database:.pawsift/logcat.db(automatically created, SQLite with WAL mode and indexes for fast queries)
- Polling Rate: 1 second (configurable inlogcat.go)
- Channel Buffer: 10,000 lines (prevents scanner backpressure during DB write contention)
- Dedup Strategy:uint64hash viahash/maphash(zero-allocation, avoids storing full log strings)
- Parser: Regex-free manual string slicing (processLineusesstrings.IndexByte/strings.Cut)
- Retention Defaults: 10,000 max logs, 3 max sessions, 30-second cleanup interval (configurable viaset_retention_policy())
- Version: Check viapawsift -version

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.

Captures and manages stdout logs from multiple processes via a named pipe system for real-time debugging and analysis.

Seamlessly bring real-time production context—logs, metrics, and traces—into your local environment to auto-fix code faster.

AI-powered live runtime debugging with Lightrun production context.

Run, debug, and triage tests via natural language across HyperExecute, Automation, SmartUI, and Accessibility on the TestMu AI cloud.

Understand, develop, and debug authorization policies in Oso Cloud.

A comprehensive proxy that combines multiple MCP servers into a single MCP. It provides discovery and management of tools, prompts, resources, and templates across servers, plus a playground for debugging when building MCP servers.

Proxyman MCP allows AI to inspect HTTP traffic, create debugging rules, and control Proxyman - all through natural language conversations.

Debug your remote Node.js and Next.js applications directly from your AI IDE like Cursor.

Live browser debugging for AI assistants — DOM, console, network via MCP.

Drives an Android emulator or a real device over adb: screenshots, UI hierarchy with true device-pixel coordinates, tap and type, app lifecycle, logcat, and Gradle builds and tests.