Registry / devops / subagent-auto-manager

subagent-auto-manager

library0.1.17jsnpmunverified

CLI and Codex hooks for tracking subagent lifecycle events (SubagentStart, SubagentStop, PostToolUse) in a local SQLite ledger. Version 0.1.17 requires Node.js >=22.14.0 for built-in node:sqlite. Designed for Codex multi-agent tasks, it records subagent state into a project-local SQLite database and provides commands to list running/stopped/closed subagents, reset state, and wait for completion. Unlike reading rollout logs, it offers a compact per-session view. Released as an npm package with no extra dependencies.

devops

npm install subagent-auto-manager

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SUBAGENT-AUTO-MANA

subagent-auto-manager

devopsjavascriptv0.1.17

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CLI

✓ npx -y subagent-auto-manager@latest

✗ npm install -g subagent-auto-manager && subagent-auto-manager

Package is meant to be run via npx; global install is not recommended. Also can be run locally with node bin/cli.js.

Hook JSON config

✓ Place hook definitions in .codex/hooks.json or ~/.codex/hooks.json as shown in README.

✗ Using require() or import to load the package

This is a CLI tool, not a library. Hooks are configured via JSON, not code imports.

Version pinning

✓ npx -y subagent-auto-manager@0.1.17

✗ npx subagent-auto-manager without version or @latest

Always pin to a specific version for reproducibility; @latest may cause unexpected updates.

Run the CLI with no arguments to list currently running, not-closed subagents for the current Codex session.

npx -y subagent-auto-manager@latest

Debug

Known issues

gotchaRequires Node.js >=22.14.0 due to built-in node:sqlite module. Older versions will throw MODULE_NOT_FOUND.

fix

Upgrade Node.js to >=22.14.0 or use a version that ships node:sqlite.

affects: <22.14.0

gotchaSome flags like --all, list, and --closed require --human flag for broad queries. Without --human, the command may silently do nothing or error.

fix

Add --human flag to those commands, for example: npx subagent-auto-manager@latest --all --human

affects: 0.1.0-0.1.17

gotchaHook setup requires Codex to trust the hooks after changes. If hooks are not trusted, they won't fire.

fix

Open /hooks in Codex and trust the updated hook definitions if Codex marks them for review.

affects: all

deprecatedCLI flags use kebab-case (--after-timestamp) but some shorthand flags like --running are not consistent across versions.

fix

Always use full flag names and refer to --help output for the specific version.

affects: 0.1.0-0.1.17

gotchaThe wait command polls the SQLite database and may not detect subagents that were started before the hook was installed.

fix

Ensure hooks are configured before subagent starts, or manually trigger the hook for existing subagents.

affects: all

Errors

Common errors & fixes

Node.js v22.14.0 or newer is required using the built-in node:sqlite module.

Node.js version below 22.14.0 lacks node:sqlite support.

fix

Upgrade Node.js to >=22.14.0.

ENOENT: no such file or directory, open '.codex/hooks.json'

Missing hooks configuration file or wrong path.

fix

Create a .codex/hooks.json file in the project root with valid hook definitions. See README for example.

Error: --all requires --human flag for broad queries

Using --all, list, or --closed without --human flag.

fix

Add --human flag to the command, e.g., npx subagent-auto-manager@latest --all --human

SQLITE_ERROR: no such table: subagent_events

Database not initialized or hook never fired.

fix

Run the hook command at least once (e.g., npx subagent-auto-manager@latest hook) to create the table.

Upgrade

Version history

0.1.17latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/NyaMisty/subagent-auto-manager ↗

packagesubagent-auto-manager ↗

homepagehttps://github.com/NyaMisty/subagent-auto-manager#readme ↗