Catpane Logcat

CatPane Android logcat MCP

Use this skill when you need Android logcat output from CatPane's MCP runtime. It is for live debugging, reproductions, and incremental monitoring of Android device logs.

Use it when

• you need to discover whether a useful capture already exists
• you need to start a scoped capture for one Android device, app, or PID
• you need focused log queries instead of dumping raw logcat
• you need to poll for new Android logs during an investigation

Tool surface

• get_status — inspect captures and optionally include all currently available capture devices
• list_devices — list all currently available capture devices; focus on Android entries
• start_capture — start buffering logcat for a device; use package or pid to scope
• get_logs — read buffered logs with filters and cursor pagination
• clear_logs — reset the buffered window for a capture without stopping it
• stop_capture — stop and remove a capture

Supporting docs:

• tools/status.md — get_status
• tools/list-devices.md — list_devices
• tools/capture.md — start_capture, clear_logs, stop_capture
• tools/get-logs.md — get_logs

Recommended workflow

1. Check runtime state first.

• Call get_status with {"includeDevices": true}.
• If a suitable capture already exists and is running, reuse it.
• If you only need device identifiers, list_devices is the lighter call.
• Both calls can include iOS simulators too, so filter to platform: "Android" for this skill.

2. Start capture only when needed.

• Call start_capture with device when multiple devices may be connected.
• Use either package or pid to scope the capture to one app.
• Use restart: true only when replacing an existing capture on the same device.

3. Query with focused filters.

• Start with limit, minLevel, tagQuery, and text.
• Prefer targeted queries over large unfiltered pulls.

4. Page with cursors.

• get_logs is cursor-based.
• Reuse the same order, pass page.nextCursor as the next cursor, and stop when page.hasMore is false.

5. Use `since` for incremental polling.

• Keep the last processed threadtime timestamp.
• Pass it back as since on the next call.
• since is inclusive, so expect one boundary overlap and dedupe by seq if needed.

6. Clear logs for a fresh observation window.

• Use clear_logs before reproducing an issue when you want a clean buffer.
• Use stop_capture only when the capture is no longer needed.

Query rules

• Always prefer captureId or device once more than one capture exists. Unqualified calls only auto-resolve when exactly one capture is registered.
• get_logs reads the in-memory ring buffer for a capture. Older entries can age out when the buffer reaches capacity.
• cursor is exclusive:
• order: "desc" returns older entries with seq < cursor
• order: "asc" returns newer entries with seq > cursor
• Use page.hasMore to decide whether to continue paging. page.nextCursor is still the correct next anchor.
• minLevel is a threshold, not an exact match. Example: warn returns warn, error, and fatal.
• tagQuery uses CatPane syntax:
• tag:ActivityManager — exact include
• tag-:chatty — exact exclude
• tag~:^(MyApp|Auth) — regex include
• text is a case-insensitive substring filter over tag and message.
• since must use logcat threadtime format: MM-DD HH:MM:SS.mmm

Quick start

get_status

{
  "includeDevices": true
}

start_capture

{
  "device": "emulator-5554",
  "package": "com.example.app"
}

get_logs

{
  "device": "emulator-5554",
  "order": "desc",
  "limit": 100,
  "minLevel": "error",
  "tagQuery": "tag~:^(MyApp|Auth) tag-:OkHttp",
  "text": "timeout"
}

Capture lifecycle tools

start_capture

Use start_capture to begin buffering Android logcat for later get_logs calls.

Key arguments

• device — strongly recommended when more than one adb device could be connected
• package — resolve a package name to a PID before capture starts
• pid — explicit PID filter
• capacity — ring-buffer size for this capture
• restart — replace an existing capture for the same device

Example: capture a device

{
  "device": "emulator-5554"
}

Example: capture one package

{
  "device": "emulator-5554",
  "package": "com.example.app",
  "capacity": 20000
}

Example: capture one PID and replace an existing capture

{
  "device": "emulator-5554",
  "pid": 12345,
  "restart": true
}

Notes

• If device is omitted, auto-selection only works when exactly one adb device is connected.
• Use either pid or package, not both.
• package is resolved to a PID at start time; it is not a live package subscription.
• If a capture is already running for the same device and restart is not true, the tool can fail with a conflict.
• capacity is the per-capture ring-buffer size; older logs fall out when the buffer fills.

clear_logs

Use clear_logs when you want a clean window for a reproduction but want to keep the capture running.

Example

{
  "captureId": "capture-1"
}

Notes

• This clears the buffered entries only.
• The capture keeps running and new logs continue to arrive.
• Prefer this over stop_capture when you only want to reset the observation window.

stop_capture

Use stop_capture when you are done with a capture and want to remove it from runtime state.

Example

{
  "captureId": "capture-1"
}

Alternative selector

{
  "device": "emulator-5554"
}

Notes

• After stop_capture, later get_logs or clear_logs calls for that capture will fail until a new capture is started.
• Use stop_capture to free the runtime state; use clear_logs to keep streaming but reset the buffer.

get_logs

Use get_logs to query buffered Android logcat entries from an existing capture. It is optimized for targeted retrieval, not bulk dumping.

Core arguments

• captureId or device — select the capture to query
• order — desc (newest first, default) or asc (forward paging)
• limit — default 100, maximum 1000
• cursor — exclusive sequence anchor for pagination
• minLevel — minimum level threshold
• tagQuery — CatPane tag filters
• text — case-insensitive substring across tag and message
• since — inclusive threadtime lower bound in MM-DD HH:MM:SS.mmm

Log level filtering

minLevel is a threshold, not an exact match.

Accepted values:

• full names: verbose, debug, info, warn, error, fatal
• aliases: V, D, I, W, E, F

Examples:

• minLevel: "warn" returns warn, error, and fatal
• minLevel: "E" returns error and fatal

Tag filter syntax

tagQuery uses CatPane's tag syntax. Multiple filters are space-separated.

• tag:MyTag — include exact tag
• tag-:NoiseTag — exclude exact tag
• tag~:^(MyApp|Auth) — regex include

Examples:

• tag:ActivityManager
• tag:MyApp tag-:OkHttp
• tag~:^(MyApp|Auth) tag-:chatty

These tag filters combine with minLevel, text, and since using AND semantics.

Example: focused error query

{
  "device": "emulator-5554",
  "order": "desc",
  "limit": 100,
  "minLevel": "error",
  "tagQuery": "tag~:^(MyApp|Auth) tag-:OkHttp",
  "text": "timeout"
}

Example: page older results with the returned cursor

{
  "captureId": "capture-1",
  "order": "desc",
  "cursor": 8421,
  "limit": 200
}

Example: incremental polling with since

{
  "captureId": "capture-1",
  "order": "asc",
  "since": "03-10 06:30:47.000",
  "minLevel": "info",
  "tagQuery": "tag~:^(MyApp|Auth)"
}

Pagination behavior

• get_logs uses cursor-based pagination.
• With no cursor, order: "desc" starts at the newest buffered entries and order: "asc" starts at the oldest buffered entries.
• cursor is exclusive.
• For order: "desc", pass page.nextCursor back to fetch older entries.
• For order: "asc", pass page.nextCursor back to fetch newer entries after the last seen sequence.
• Keep the same filters and the same order while paging one result set.
• Use page.hasMore to decide whether to continue paging.
• page.nextCursor remains the correct next anchor even when page.hasMore is false.

Incremental polling behavior

• since is inclusive: entries at exactly that timestamp are returned again.
• Keep the last processed timestamp and dedupe the boundary entry by seq if you need strict once-only processing.
• Use since when you want time-based polling across repeated calls, especially after clear_logs or when you do not want to keep cursor state indefinitely.

Notes

• If more than one capture exists, do not rely on an unqualified call; pass captureId or device.
• entries[] are buffered logs only. If capture.buffer.dropped grows or the buffer is near capacity, older logs may already be gone.
• Response pagination fields live under page: returned, firstSeq, lastSeq, nextCursor, hasMore.

list_devices

Use list_devices when you need current capture-device identifiers before starting a capture, or when get_status was called without includeDevices.

Arguments

{}

What to read from the response

• deviceCount
• devices[].serial — pass this to start_capture.device or as a device selector in other tools
• devices[].friendlyName and devices[].description — useful when choosing between similar devices
• devices[].platform — use "Android" entries for this skill
• devices[].isTcp — useful when both USB and TCP devices are present

Operational notes

• list_devices does not create a capture.
• If deviceCount is 0, start_capture will fail until adb sees a device.
• This shared tool can also return iOS capture targets such as booted simulators and wired physical devices; ignore non-Android entries for this skill.
• If you also need capture state, prefer get_status with {"includeDevices": true} so you can inspect both captures and devices in one call.

get_status

Use get_status as the default first call. It shows what captures exist, whether they are running, and how full each buffer is.

Common arguments

All captures

{}

All captures plus currently available devices

{
  "includeDevices": true
}

One capture by ID

{
  "captureId": "capture-1"
}

One capture by device

{
  "device": "emulator-5554"
}

What to inspect

• captureCount and runningCaptureCount
• captures[].running
• captures[].device and captures[].captureId
• captures[].package or captures[].pidFilter
• captures[].buffer.len, captures[].buffer.capacity, and captures[].buffer.dropped
• captures[].parsedEntries and captures[].parseErrors
• devices[] when includeDevices is true
• devices[].platform — use "Android" entries for this skill
• devices[].isTcp — useful when both USB and TCP Android devices are present

Operational notes

• With no selector, captures includes every registered capture.
• With captureId or device, captures is narrowed to that capture, but the top-level counts still describe the whole runtime.
• includeDevices returns both connected Android devices and any iOS capture targets CatPane can currently use.
• Use this before start_capture to avoid duplicate captures.
• Use this before get_logs to learn the right captureId or device selector.