ecc sessions: Session Inspection and State Queries

ECC records every agent session, skill run, governance event, and linked work item in a local SQLite state store. The commands on this page let you query that store, inspect Claude transcript files for loop health, and emit canonical session snapshots — giving operators a complete picture of what the AI harness is doing and has done.

`ecc sessions`

List recent ECC sessions from the SQLite state store, or drill into a single session to see its workers, skill runs, and decisions.

Usage

ecc sessions [<session-id>] [--db <path>] [--json] [--limit <n>]

Flags

session-id

string

When provided, show full detail for a single session: workers, skill runs, and decisions. When omitted, the command lists recent sessions.

ecc sessions sess_01abc123

--db

string

Path to the ECC SQLite state database. Defaults to the standard location under the user’s home directory.

--json

flag

Emit machine-readable JSON instead of the human-readable summary.

--limit

number

Maximum number of recent sessions to list. Default: 10.

Session list output

Recent sessions:

- sess_01abc123 [claude/claude-global] active
  Repo: /Users/you/projects/my-app
  Started: 2025-01-15T10:22:00.000Z
  Ended: (active)
  Workers: 3

- sess_01def456 [codex/codex-global] completed
  Repo: /Users/you/projects/api-service
  Started: 2025-01-14T08:00:00.000Z
  Ended: 2025-01-14T09:30:00.000Z
  Workers: 1

Total sessions: 2

Session fields

Field	Description
`id`	Unique session identifier
`harness`	AI harness that created the session (e.g. `claude`, `codex`)
`adapterId`	Target adapter used (e.g. `claude-global`, `cursor-project`)
`state`	`active`, `completed`, or `error`
`repoRoot`	Filesystem path of the repository root for the session
`startedAt`	ISO timestamp when the session began
`endedAt`	ISO timestamp when the session ended, or `(active)`
`workerCount`	Number of worker agents in the session

Session detail output

When a session-id is provided:

Session: sess_01abc123
Harness: claude
Adapter: claude-global
State: active
Repo: /Users/you/projects/my-app
Started: 2025-01-15T10:22:00.000Z
Ended: (active)

Workers: 2
  - worker-a active
    Branch: feat/auth-refactor
    Worktree: /Users/you/projects/my-app/.worktrees/worker-a
  - worker-b active
    Branch: feat/api-layer
    Worktree: /Users/you/projects/my-app/.worktrees/worker-b

Skill runs: 4
  - run_01 success tdd@1.2.0
    Task: Write unit tests for AuthService
    Duration: 42000 ms
  ...

Decisions: 1
  - dec_01 pending
    Title: Choose HTTP client library
    Alternatives: axios, fetch, got

`ecc status`

Query the ECC SQLite state store for a full system snapshot. ecc status is the operator’s quick-health command — it summarises active sessions, recent skill run success rates, install health across all targets, pending governance events, linked work items, and GitHub epic coordination state.

Usage

ecc status [--db <path>] [--json|--markdown] [--write <path>] [--limit <n>] [--exit-code]

Flags

--db

string

Path to the ECC SQLite state database. Defaults to the standard home-directory location.

--json

flag

Emit the full status payload as JSON. Cannot be combined with --markdown.

--markdown

flag

Render the status report as Markdown. Cannot be combined with --json.

--write

string

Write the formatted output to a file at the given path. Requires --json or --markdown; cannot be used with plain text output.

ecc status --markdown --write docs/status.md

--limit

number

Maximum number of items to show in each section (active sessions, recent skill runs, pending governance events, work items). Default: 5.

--exit-code

flag

Return exit code 2 when the readiness status is not ok, enabling use as a CI gate.

ecc status --exit-code || echo "ECC readiness needs attention"

Status sections

Section	What it shows
Readiness	Overall status (`ok` / `attention`), attention item count, and per-dimension counts
Active sessions	Sessions currently in `active` state with harness, adapter, repo, and worker count
Skill runs	Success/failure/unknown counts and rates over the recent window
Install health	Per-target install status, profile, module count, and source version
Governance	Pending governance events with type and session association
Work items	Open, blocked, and closed item counts with source, status, and owner
GitHub epic coordination	Available, claimed, ready, blocked, validated, and published epic counts

Examples

ecc status

`ecc work-items`

Track linked Linear issues, GitHub issues and PRs, handoff items, and manual roadmap items in the ECC SQLite state store. Work items surface in ecc status as blocked operator follow-up and are visible in the control pane.

Usage

ecc work-items list [--db <path>] [--json] [--limit <n>]
ecc work-items show <id> [--db <path>] [--json]
ecc work-items upsert [<id>] --title <title> [options]
ecc work-items close <id> [--status done] [--db <path>] [--json]
ecc work-items claim [<id>] --owner <name> [--as agent|human] [--db <path>]
ecc work-items sync-github --repo <owner/repo> [--db <path>] [--json]

Subcommands

list

Print recent work items from the state store.

ecc work-items list
ecc work-items list --json --limit 50

show

Print full detail for a single work item by its local ID.

ecc work-items show linear-ecc-20

upsert

Create or update a work item. The local <id> is optional — one is generated when omitted. All --source, --source-id, --status, --priority, --url, --owner, --repo-root, and --session-id flags are optional and can be provided individually.

ecc work-items upsert linear-ecc-20 \
  --source linear \
  --source-id ECC-20 \
  --title "Review control-plane contract" \
  --status blocked

Mark a work item as closed. Defaults to --status done.

ecc work-items close linear-ecc-20
ecc work-items close linear-ecc-20 --status wont-fix

claim

Assign a work item to an owner, recording whether the claimant is an agent or human.

ecc work-items claim linear-ecc-20 --owner @affaan --as human
ecc work-items claim linear-ecc-20 --owner claude-worker-a --as agent

sync-github

Fetch open issues and PRs from a GitHub repository and upsert them as github-source work items in the state store.

ecc work-items sync-github --repo affaan-m/ECC

Work item fields

Field	Description
`source`	Source system: `linear`, `github`, `handoff`, `manual`, `github-epic`
`sourceId`	Source-local identifier, e.g. `ECC-20` or a PR number
`title`	Human-readable description of the work item
`status`	`open`, `in-progress`, `blocked`, `done`, or custom
`priority`	Optional priority label
`url`	Optional link to the source issue or PR
`owner`	Optional owner label (agent name or human handle)
`repoRoot`	Filesystem path associating the item with a specific repository

`ecc session-inspect`

Emit canonical ECC session snapshots from dmux orchestration plan files or Claude session history targets. Also supports skill health and amendment workflows via the skills:* target namespace.

Usage

ecc session-inspect <target> [--adapter <id>] [--target-type <type>] [--write <output.json>]
ecc session-inspect --list-adapters

Targets

Target	Description
`<plan.json>`	Path to a dmux/orchestration plan file
`<session-name>`	Dmux session name when the coordination directory exists
`claude:latest`	Most recent entry in `~/.claude` session history
`claude:<id\|alias>`	Specific Claude session by ID or alias
`<session.tmp>`	Direct path to a Claude session file
`skills:health`	Inspect skill failure/success patterns from observations
`skills:amendify`	Propose a `SKILL.md` patch from failure evidence
`skills:evaluate`	Compare baseline vs amended skill outcomes

Flags

--adapter

string

Override the session adapter ID used to inspect the target.

--target-type

string

Override automatic target type detection (e.g. claude-history).

--write

string

Write the JSON snapshot to a file at the given path instead of (or in addition to) printing to stdout.

--list-adapters

flag

Print all registered session adapter IDs.

--skill

string

When using skills:amendify or skills:health, specify the skill ID to focus on.

Examples

ecc session-inspect claude:latest

`ecc loop-status`

Inspect Claude transcript .jsonl files under ~/.claude/projects/ for stale loop wakeups and pending tool results. Surfaces two signal types: schedule_wakeup_overdue (a ScheduleWakeup tool call whose due time has passed without assistant progress) and pending_bash_tool_result (a Bash tool call with no matching result entry and an age exceeding the timeout threshold).

Usage

ecc loop-status [--json] [--home <dir>] [--limit <n>] [--watch]
ecc loop-status --transcript <session.jsonl> [--json] [--watch]

Flags

--json

flag

Emit machine-readable status JSON instead of the human-readable text report.

--home

string

Override the home directory to scan. Defaults to $HOME.

--transcript

string

Inspect a single transcript file directly instead of scanning ~/.claude/projects/. Repeatable.

ecc loop-status --transcript ~/.claude/projects/-repo/session.jsonl

--limit

number

Maximum number of recent transcripts to inspect (by modification time). Default: 10.

--bash-timeout-seconds

number

Age in seconds before a pending Bash tool call is considered stale. Default: 1800 (30 minutes).

--wake-grace-multiplier

number

Grace multiplier applied to the scheduled delay before a ScheduleWakeup is considered overdue. Default: 2.

--now

string

Override the current time for testing. Accepts ISO 8601, epoch milliseconds, or the literal string now.

--exit-code

flag

Return exit code 2 when any session has an attention signal, 1 on scan errors. With --watch, requires --watch-count.

--watch

flag

Continuously refresh status until interrupted with Ctrl-C. Use --watch-interval-seconds to control the refresh rate.

--watch-count

number

Stop after N watch refresh cycles. Required when combining --watch and --exit-code.

--watch-interval-seconds

number

Seconds between watch refreshes. Default: 5.

--write-dir

string

Write index.json and per-session snapshot files to the given directory for external dashboards or CI artifact collection.

Signal types

Signal	Trigger condition
`schedule_wakeup_overdue`	A `ScheduleWakeup` tool call is past its due time (including grace period) with no subsequent assistant progress
`pending_bash_tool_result`	A `Bash` tool call has no matching result entry and its age exceeds `--bash-timeout-seconds`
`transcript_parse_errors`	One or more JSONL lines in the transcript could not be parsed

Output format

ECC loop status (2025-01-15T10:30:00.000Z)
- sess_abc123 [attention] /Users/you/.claude/projects/-my-app/session.jsonl
  last event: 2025-01-15T08:00:00.000Z; events: 142
  signals: schedule_wakeup_overdue
  action: Open the transcript or interrupt the parked session; the scheduled wake is overdue.
- sess_def456 [ok] /Users/you/.claude/projects/-api/session.jsonl
  last event: 2025-01-15T10:29:00.000Z; events: 38
  signals: none
  action: No stale ScheduleWakeup or Bash waits detected.

Examples

ecc loop-status

CLI Reference

Skills Library

Hooks Reference

Configuration

ecc sessions: Session Inspection and State Queries

`ecc sessions`

Usage

Flags

Session list output

Session fields

Session detail output

`ecc status`

Usage

Flags

Status sections

Examples

`ecc work-items`

Usage

Subcommands

Work item fields

`ecc session-inspect`

Usage

Targets

Flags

Examples

`ecc loop-status`

Usage

Flags

Signal types

Output format

Examples

Build docs developers (and LLMs) love

CLI Reference

Skills Library

Hooks Reference

Configuration

Documentation Index

​ecc sessions

​Usage

​Flags

​Session list output

​Session fields

​Session detail output

​ecc status

​Usage

​Flags

​Status sections

​Examples

​ecc work-items

​Usage

​Subcommands

​Work item fields

​ecc session-inspect

​Usage

​Targets

​Flags

​Examples

​ecc loop-status

​Usage

​Flags

​Signal types

​Output format

​Examples

Build docs developers (and LLMs) love

`ecc sessions`

Usage

Flags

Session list output

Session fields

Session detail output

`ecc status`

Usage

Flags

Status sections

Examples

`ecc work-items`

Usage

Subcommands

Work item fields

`ecc session-inspect`

Usage

Targets

Flags

Examples

`ecc loop-status`

Usage

Flags

Signal types

Output format

Examples