dsh-plugin-dew

Readme

# dsh-plugin-dew

**See what your other coding agents are doing — from inside DSH.**

You run Claude Code in one window, Codex in another, maybe Cursor too. DSH can't
see any of it. This plugin gives DSH two read-only tools that parse the session
logs those agents already write to disk, and normalize everything to one
vocabulary: **needs you / running / done / idle**.

```
> is anything waiting on me?

3 matching sessions; 11 scanned over the last 8h (needs you 1, running 2, done 8, idle 0).

NEEDS YOU
· Claude Code · web-app (2m ago) — waiting for approval: Bash
RUNNING
· Codex · api-server (18s ago) — Refactoring the auth middleware
· DSH · notebook (44s ago) — running bash
```

It is a port of the readers behind [Dew](https://github.com/cinderzhan/dew), a
macOS status bar for the same data.

## Install

In DSH Desktop: **Settings → Plugins**, search for `dsh-plugin-dew`, install.

Or wire it into a profile by hand — add the dependency and list it as a bundle:

```jsonc
// ~/.dsh/profiles/web/package.json
{
  "dependencies": { "dsh-plugin-dew": "^0.1.0" },
  "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-plugin-dew"] } }
}
```

Requires Node 20+. Reading DSH's own compressed transcripts additionally needs a
runtime with `zlib.zstdDecompressSync` (Node 23.8+); without it the other three
agents still work.

## Tools

### `agent_sessions`

Lists sessions and what each one is doing.

| Parameter | Type | Meaning |
|---|---|---|
| `agents` | string[] | Restrict to `claude_code`, `codex`, `cursor`, `dsh`. Omit for all. |
| `state` | string | One of the four states, or `active` (default, everything but idle), or `all`. |
| `within_hours` | integer | Lookback. Defaults to 8. |
| `limit` | integer | Cap on returned rows, highest priority first. Defaults to 25. |

Good for: *"is my Claude Code run finished?"*, *"which agent is blocked on me?"*,
and — before you start editing — *"is another agent already working in this
directory?"*

### `agent_scheduled_tasks`

Lists recurring agent jobs and when each fires next: Codex automations (RRULE)
and Claude Code scheduled tasks (cron), evaluated locally.

| Parameter | Type | Meaning |
|---|---|---|
| `agents` | string[] | Restrict to specific agents. |
| `include_disabled` | boolean | Include switched-off tasks. Defaults to false. |

## What it reads

Everything is **read-only**. The plugin never writes into another agent's data
directory, never touches a keychain or credential store, and makes no network
requests.

| Agent | Sessions | Scheduled tasks | Source |
|---|:-:|:-:|---|
| Claude Code | ✅ | ⚠️ | `~/.claude/projects/**/*.jsonl`, `~/.claude/scheduled-tasks/` |
| Codex | ✅ | ✅ | `~/.codex/sessions/`, `~/.codex/automations/` |
| Cursor | ✅ | — | `~/.cursor/projects/<slug>/agent-transcripts/` |
| DSH | ✅ | — | `$DSH_HOME` (default `~/.dsh`) and the DSH Desktop harness dir |

⚠️ Claude Code scheduled tasks are implemented against the documented contract
but have never been observed on a real machine — the parser is defensive and
returns nothing rather than guessing.

## How the states are decided

Each agent is different, and the honest summary is that **only some of this is
explicit**:

- **Codex** and **DSH** write explicit lifecycle events (`task_started` /
  `task_complete`, `turn/start` / `turn/end`), so `running` and `done` are read,
  not inferred.
- **Claude Code** is inferred from the transcript tail: an `assistant` row with
  `stop_reason: "tool_use"` and no matching `tool_result` means a tool was
  requested and has not returned.
- **Cursor** has the least to work with — no `tool_result` rows and no
  timestamps — so its state rests on the last row plus the file's mtime.

`needs_you` is **always** an inference. No agent writes a "waiting for approval"
event, so it is derived from a pending tool call that has gone quiet. The
threshold is per tool rather than a single number, because an approved long
`Bash` writes nothing to its log while it runs — silences of two to four minutes
are normal — and a flat threshold reports every slow command as a permission
prompt.

## Privacy

`agent_sessions` returns a one-line summary of each session, which is an excerpt
of that conversation, and those summaries go to your model provider like any
other tool result. If that is not what you want:

```yaml
config:
  redactSummaries: true   # report states and projects, no conversation text
```

## Configuration

```yaml
config:
  agents: []              # limit the scan, e.g. ["claude_code", "codex"]
  defaultWindowHours: 8   # lookback when a call does not specify one
  redactSummaries: false
```

## Development

```bash
npm test        # node --test, no build step, no runtime dependencies
```

The plugin ships plain ESM — there is nothing to compile. `@deepseek-ai/dsh-tools`
and `@deepseek-ai/schemastery` are peer dependencies supplied by any DSH profile.

## License

[MIT](LICENSE)