Docs / Configuration

Sensible defaults. Tunable if you want.

Everything is editable from Settings in the dashboard. The config file is human-readable JSON in your data directory — handy for backup or syncing across machines.

Where things live

Windows

Config — %APPDATA%\TeamLaboration\config.json
Database — %APPDATA%\TeamLaboration\teamlaboration.db
Logs — %APPDATA%\TeamLaboration\logs\agent.log
App — %LOCALAPPDATA%\TeamLaboration\

macOS

Config — ~/Library/Application Support/TeamLaboration/config.json
Database — ~/Library/Application Support/TeamLaboration/teamlaboration.db
Logs — ~/Library/Application Support/TeamLaboration/logs/agent.log
App — /Applications/TeamLaboration.app

The database uses SQLite WAL mode so the scheduler thread and the web server thread can read and write at the same time without blocking each other. Don't delete teamlaboration.db-wal or -shm sidecar files while the daemon is running.

config.json

The full schema. Every field is optional — missing keys fall back to defaults. Edits via Settings are written back here on save.

{
  "ai_provider": "claude",
  "ai_enabled": true,
  "ai_api_key": "keyring:",
  "poll_interval_seconds": 300,
  "summarization": {
    "at_hour": 9
  },
  "week_start_day": 0,
  "weekly_report_day": 1,
  "output_dir": null,
  "port": 7842,
  "notifications": {
    "file":  { "enabled": true,  "path": "%USERPROFILE%\\Documents\\TeamLaboration" },
    "email": { "enabled": false, "smtp_host": "", "smtp_port": 587, "from": "", "to": "" },
    "slack": { "enabled": false, "webhook_url": "" }
  },
  "projects": {
    "include_all": true,
    "exclude": []
  }
}

Fields, one by one

ai_api_key — keyring sentinel

Always the literal string "keyring:" on disk. The actual key lives in Windows Credential Manager or macOS Keychain via the keyring library. An empty value ("") means no key is set. Never edit this field by hand — use Settings to update it.

ai_enabled — boolean, default true

When false, the daemon collects sessions and tracks them in the database but never calls the Anthropic API. You then drive summarization manually from Claude Code via the MCP slash commands — handy when you'd rather not give the daemon a key. See MCP.

poll_interval_seconds — default 300

How often the collector walks ~/.claude/projects/. Five minutes is fine for everyone — Claude Code writes files incrementally, so a longer poll won't miss anything, it just delays detection. Don't go below 60 seconds.

summarization.at_hour — 0–23, default 9

Hour of day (local time) for the daily batch summarization job. All pending sessions get summarized in one cron firing. If the configured hour has already passed when the daemon starts, it runs immediately and then waits for tomorrow.

week_start_day — 0=Mon, 6=Sun

Where the weekly window begins. Default is Monday (ISO week). Affects which sessions roll into which weekly report.

weekly_report_day — 0–6

Day of week the automatic weekly rollup is generated. Default Monday. You can always click Generate Report in the Week view to run it sooner.

port — default 7842

The local HTTP port. On startup the daemon tries port, then port+1, then port+2 — so a busy 7842 falls back to 7843 or 7844. The actual bound port is logged. Bound to 127.0.0.1 only, never your LAN.

output_dir — file output path

When set, weekly reports are mirrored to this folder as Markdown and HTML. Useful for committing reports to a personal journal repo, or for syncing via Dropbox / iCloud / Drive.

notifications — file / email / slack

Each channel has its own enabled flag and credentials. File output is on by default. Email needs SMTP host + port + from/to. Slack and Teams use webhook URLs. All credentials stay on your machine.

projects.include_all / exclude

By default every project under ~/.claude/projects/ is collected. Add project directory names to exclude to skip them — useful if a particular project is sensitive or experimental and you don't want it in your weekly report.

Retention

The Solo tier keeps four weeks of data. On every daemon start, a purge job runs:

· Summaries and weekly reports — deleted after 28 days.
· Raw session ledger — the lightweight session row (file path, mtime, status — no content) is deleted after 56 days.

Export reports as JSON or Markdown from the dashboard before they age out if you want to keep them. The raw Claude Code logs in ~/.claude/projects/ are never modified or copied by TeamLaboration — only read.

Debug logging

Set TEAMLABORATION_DEBUG=1 in your environment before starting the daemon to enable verbose logs. The agent log rotates at 10 MB with five backups, so a noisy debug session won't fill your disk.

Disabling autostart

The agent registers a Windows Task Scheduler entry or a macOS LaunchAgent the first time it runs. To unregister it:

teamlaboration-agent --uninstall

This removes the autostart entry only — your config, database, and the installed app are untouched. To skip autostart for one run: teamlaboration-agent --no-autostart.

← Getting started Next: MCP server →