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: support@heijnesdigital.com