claude-assist

Backend services for a Claude-based personal executive assistant. Provides postgres-backed APIs for session recall, email triage, and calendar queries.

Plugin Installation

Install as a Claude Code plugin to use the session-recall skill:

/plugin marketplace add JarvusInnovations/claude-assist
/plugin install claude-assist@jarvus-claude-assist

After installation, the /session-recall skill becomes available. Use it when you need to search past Claude sessions.

Note: The plugin requires a running backend server with PostgreSQL. See Quick Start below.

Prerequisites

• Docker with Compose plugin

Quick Start

cd apps/server
docker compose up --build -d

The API will be available at http://localhost:2529

Sessions from ~/.claude/ on the host machine sync automatically. To sync from other machines:

bunx @jarvus/claude-assist-sessions push -m laptop -s https://your-server:2529

Environment Setup

Copy the example environment file and configure:

cp apps/server/.env.example apps/server/.env

Edit .env to set your ANTHROPIC_API_KEY if you want AI-generated session outlines. Get your key at https://console.anthropic.com/

Local Development

For contributors who want to develop locally with hot reload:

# Install bun via asdf (uses .tool-versions) or directly from bun.sh
asdf install  # or: curl -fsSL https://bun.sh/install | bash

# Install dependencies
bun install

# Start PostgreSQL only
cd apps/server
docker compose up postgres -d

# Start development server with watch mode
bun run dev

VS Code debugging: Use the provided launch configurations in .vscode/launch.json:

• "Debug Server" - runs with watch mode and debugger attached
• "Debug Server (no watch)" - single run with debugger
• "Attach to Bun" - attach to running bun process

Project Structure

packages/
  core/         # Shared utilities (scheduler, migrations, search)
apps/
  server/       # Fastify host application
skills/
  session-recall/  # Session search skill

Development

# Build all packages
bun run build

# Run tests
bun test

# Type check
cd packages/core && bun run build
cd apps/server && bun run build

API Endpoints

Health Check

GET /health

Scheduler

GET  /scheduler/tasks          # List registered tasks
POST /scheduler/tasks/:name    # Trigger task manually

Docker

cd apps/server

# Start full stack
docker compose up --build -d

# Start PostgreSQL only (for local development)
docker compose up postgres -d

# View logs
docker compose logs -f

Local Port Overrides

By default, services bind to localhost only on ports 2528 (PostgreSQL) and 2529 (API). To expose on additional interfaces (e.g., Tailscale), create docker-compose.override.yml (gitignored):

services:
  postgres:
    ports:
      - "127.0.0.1:2528:5432"
      - "<your-ip>:2528:5432"
  api:
    ports:
      - "127.0.0.1:2529:2529"
      - "<your-ip>:2529:2529"

Run docker compose config to verify the merged configuration.

Environment Variables

Variable	Default	Description
PORT	2529	Server port
HOST	0.0.0.0	Server host
DATABASE_URL	postgres://claude:dev@localhost:2528/claude_assist	PostgreSQL connection
LOG_LEVEL	info	Log level (debug, info, warn, error)
NODE_ENV	development	Environment (development, production)
ANTHROPIC_API_KEY	(none)	Enables AI-generated session outlines
OUTLINE_CONCURRENCY	5	Parallel outline generation workers

Skills

Skills are loaded on-demand by Claude. Available skills:

• session-recall - Search past Claude sessions

See skills/*/SKILL.md for usage documentation.

License

MIT