How to Debug Sync Issues and Missing Sessions in AgentsView

TLDR: Enable debug logging with AGENTSVIEW_LOG_LEVEL=debug, force a full sync using agentsview sync, and trace the pipeline from internal/sync/watcher.go through internal/sync/engine.go to internal/db/sessions.go to identify where sessions drop out of the synchronization flow.

AgentsView is an open-source tool from kenn-io/agentsview that maintains a synchronized view of AI-agent sessions by watching filesystem changes and persisting them to a local SQLite or PostgreSQL database. When sessions fail to appear or updates seem stalled, the issue typically resides in one of four layers: the file watcher, the sync engine, the parser, or the database writer. Understanding how to inspect each layer allows you to diagnose missing data without guesswork.

Understanding the AgentsView Sync Pipeline

AgentsView follows a pipeline architecture. The file watcher (internal/sync/watcher.go) monitors the data directory for changes, feeding events into the sync engine (internal/sync/engine.go). The engine orchestrates parsers (internal/parser/zed.go, internal/parser/workbuddy.go, etc.) to extract session data, which is then written to the database via internal/db/sessions.go. Finally, the server API (internal/server/sessions.go) surfaces this data to the UI. If any stage fails, sessions appear missing.

Enable Debug Logging to Expose Runtime Behavior

Before investigating specific components, enable verbose logging to capture the internal state of the sync process.

Set the Log Level Environment Variable

Run AgentsView with the AGENTSVIEW_LOG_LEVEL environment variable set to debug. This outputs granular logs from the watcher, engine, and database layers, initialized in cmd/agentsview/main.go.

export AGENTSVIEW_LOG_LEVEL=debug
agentsview serve

Identify Key Log Patterns

Search the logs for these specific markers:

• watcher: new file – Confirms the filesystem watcher detected a change.
• starting sync / finished sync – Emitted by internal/sync/engine.go to mark sync boundaries.
• parser: – Indicates activity in internal/parser/; errors here mean a file was seen but could not be processed.
• SQLITE_BUSY or database is locked – Signals contention in internal/db/sessions.go.

Verify the File Watcher is Active

If incremental updates fail while manual imports work, the watcher may be inactive or misconfigured.

Check that AGENTSVIEW_DATA_DIR points to the correct path containing your agent subdirectories. If the directory is correct but no watcher: logs appear, your operating system may have hit its file notification limit. On Linux, increase the inotify watch limit:

sudo sysctl fs.inotify.max_user_watches=524288

Force a Full Sync to Bypass Incremental Failures

When the watcher works but sessions remain missing, force a complete re-scan. This bypasses incremental event handling and re-processes every file.

agentsview sync

For PostgreSQL backends, use:

agentsview pg sync

After completion, check the sync_progress metrics written by internal/sync/progress.go. Validate that total_files matches the actual file count in your data directory and that failed_files is zero.

find $AGENTSVIEW_DATA_DIR -type f | wc -l

Inspect Parser Execution for Silent Failures

If the sync runs but specific sessions are absent, the parser may be failing. Look for parser: error lines in the debug log. To isolate a specific file, run the parser manually:

go run ./cmd/agentsview --parse $AGENTSVIEW_DATA_DIR/zed/problematic-session.json

This outputs the exact error preventing the session from being structured for the database.

Query the Database Directly

Confirm that successfully parsed data actually reached the database. Open the default SQLite database located at $HOME/.agentsview/agentsview.db:

sqlite3 $HOME/.agentsview/agentsview.db

Verify recent sessions exist:

SELECT id, agent, created_at 
FROM sessions 
ORDER BY created_at DESC 
LIMIT 10;

If rows are missing despite successful parser logs, inspect internal/db/sessions.go for transaction rollback conditions or constraint violations.

Resolve Database Lock Contention

High-frequency updates can trigger SQLITE_BUSY errors visible in the logs. This occurs when the sync engine attempts concurrent writes to internal/db/sessions.go. Solutions include:

• Increasing the SQLite connection pool size if configurable.
• Switching to the PostgreSQL backend for higher concurrency: agentsview pg serve.

Validate the Server API and UI Layer

If the database contains sessions but the UI shows none, the issue lies in internal/server/sessions.go. Query the API directly to confirm:

curl -s http://localhost:8080/api/sessions?limit=5 | jq .

An empty response here indicates filtering logic (such as hidden agents) or a data retrieval bug in the server layer, rather than a sync failure.

Summary

• Enable AGENTSVIEW_LOG_LEVEL=debug to expose watcher events, engine boundaries, and database errors.
• Inspect internal/sync/watcher.go logs and system inotify limits if incremental updates stall.
• Force a full sync with agentsview sync to isolate incremental watcher issues.
• Check internal/sync/progress.go metrics (total_files, processed_files, failed_files) against actual filesystem counts.
• Run parsers manually using --parse to isolate file-specific errors.
• Query agentsview.db directly to verify internal/db/sessions.go persistence.
• Switch to PostgreSQL (agentsview pg serve) if SQLITE_BUSY errors indicate lock contention.
• Use curl against /api/sessions to determine if the problem is in internal/server/sessions.go rather than the sync pipeline.

Frequently Asked Questions

Why are my sessions missing after a file change?

Missing sessions after a file change usually indicate the file watcher in internal/sync/watcher.go missed the event or the parser rejected the file. Check debug logs for watcher: entries to confirm detection, then run the parser manually on the file to catch validation errors.

How do I fix "database is locked" errors during sync?

This error originates from internal/db/sessions.go when the SQLite database receives concurrent write requests. You can reduce sync frequency or migrate to PostgreSQL by running agentsview pg serve, which handles concurrency better than the default SQLite backend.

What is the difference between incremental and full sync in AgentsView?

Incremental sync relies on the file watcher (internal/sync/watcher.go) to react to real-time filesystem events. Full sync, triggered by agentsview sync, scans the entire AGENTSVIEW_DATA_DIR and re-processes every file regardless of previous state, which is useful for recovering from missed events or corruption.

How can I verify if the file watcher is detecting my new session files?

Add a new file to your data directory and look for watcher: new file entries in the logs when running with AGENTSVIEW_LOG_LEVEL=debug. If no entry appears within seconds, verify the AGENTSVIEW_DATA_DIR configuration and check your OS file notification limits (e.g., fs.inotify.max_user_watches on Linux).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}