agentsession-logger

A complete workflow tool that captures, organizes, and analyzes AI coding agent sessions — logs all tool calls, LLM interactions, decisions, and code changes into a searchable, timestamped session database.

Built with AI by Craftpipe

Installation

npm install -g agentsession-logger

Quick Start

# Initialize the database
agentsession-logger db:init

# Create a new session
agentsession-logger session:create --name "my-feature" --agent "claude"

# List all sessions
agentsession-logger session:list

# Get a specific session
agentsession-logger session:get <session-id>

# Close a session
agentsession-logger session:close <session-id>

# Search sessions
agentsession-logger search "refactor"

# View events for a session
agentsession-logger events <session-id>

# Export a session as JSON
agentsession-logger export <session-id>

# Check license status
agentsession-logger license:check

CLI Commands

db:init

Initialize (or re-initialize) the SQLite database and run all migrations.

agentsession-logger db:init

session:create

Create a new agent session.

agentsession-logger session:create --name "my-session" --agent "gpt-4" --metadata '{"project":"api-refactor"}'

| Option | Alias | Description | |---|---|---| | --name <name> | -n | Session name | | --agent <agent> | -a | Agent name | | --metadata <json> | -m | JSON metadata string |

session:close

Close an open session by ID.

agentsession-logger session:close <session-id>

session:get

Retrieve and display a session by ID.

agentsession-logger session:get <session-id>

session:list

List all sessions, with optional filters.

agentsession-logger session:list
agentsession-logger session:list --status open
agentsession-logger session:list --agent claude --limit 20

| Option | Description | |---|---| | --status <status> | Filter by status (open / closed) | | --agent <agent> | Filter by agent name | | --limit <n> | Maximum number of results (default: 50) |

search

Full-text search across all sessions and events.

agentsession-logger search "database migration"
agentsession-logger search "refactor" --type tool_call

| Option | Description | |---|---| | --type <type> | Filter by event type | | --limit <n> | Maximum number of results |

events

Show the event timeline for a session.

agentsession-logger events <session-id>
agentsession-logger events <session-id> --type llm_interaction

| Option | Description | |---|---| | --type <type> | Filter events by type |

export

Export a session (and its events) as JSON.

agentsession-logger export <session-id>
agentsession-logger export <session-id> --output ./my-session.json

| Option | Alias | Description | |---|---|---| | --output <file> | -o | Write output to file instead of stdout |

license:check

Display current license status and enabled feature flags.

agentsession-logger license:check

Configuration

Create a .agentsessionrc.json file in your project root (or home directory) to set defaults:

{
  "databasePath": "./agentsessions.db",
  "storageLocation": "./.agentsessions",
  "defaultAgentName": "my-agent",
  "logLevel": "info"
}

Environment Variables

| Variable | Description | |---|---| | AGENTSESSION_DB_PATH | Path to the SQLite database file | | AGENTSESSION_STORAGE_LOCATION | Path to the session storage directory | | AGENTSESSION_DEFAULT_AGENT | Default agent name | | AGENTSESSION_LOG_LEVEL | Log level (info, debug, warn, error) | | PRO_LICENSE | License key to enable premium features |

Programmatic API

You can also use agentsession-logger as a Node.js library:

const logger = require('agentsession-logger');

// Initialize the database
await logger.initializeDatabase();

// Create a session
const session = await logger.createSession({
  name: 'my-session',
  agent: 'claude',
  metadata: { project: 'api-refactor' }
});

// Record a tool call
await logger.recordToolCall(session.id, {
  tool: 'read_file',
  input: { path: 'src/index.js' },
  output: { content: '...' }
});

// Record an LLM interaction
await logger.recordLLMInteraction(session.id, {
  prompt: 'Refactor this function',
  response: 'Here is the refactored version...'
});

// Close the session
await logger.closeSession(session.id);

// Search sessions
const results = await logger.searchSessions('refactor');

// Get session events
const events = await logger.getSessionEvents(session.id);

Premium Features

Set the PRO_LICENSE environment variable to unlock premium features:

• Dashboard — Visual web UI on port 4000
• Team Collaboration — Shared session storage
• REST API — Programmatic HTTP access

Get a license at: https://craftpipe.gumroad.com

License

MIT

Built with AI by Craftpipe | Support: [email protected]