How to Configure Custom Session Directories for Unsupported Agents in agentsview

You can configure custom session directories for unsupported agents in agentsview using environment variables for single-directory overrides, TOML arrays for multiple paths, or by relocating the entire data root via AGENTSVIEW_DATA_DIR.

agentsview is an open-source session management tool that stores AI agent files under a centralized data directory. When working with custom agents or non-standard session storage locations, you can configure custom session directories for unsupported agents through flexible override mechanisms defined in the kenn-io/agentsview repository.

Understanding the Configuration Architecture

The agentsview configuration system relies on the AgentDef struct defined in internal/parser/types.go (lines 46‑55). Each agent entry specifies an EnvVar field for environment-based overrides and a ConfigKey field for TOML configuration. During startup, the application loads directory paths through a cascading hierarchy: default values are initialized first, then overridden by the config file, then environment variables, and finally CLI flags.

The loading logic resides in internal/config/config.go, where the loadEnv function (lines 88‑94) processes per-agent directory overrides, and the TOML parsing logic (lines 78‑84) handles configuration file arrays.

Method 1: Environment Variables for Single Directory Overrides

For quick redirection of a single agent's session storage, export the environment variable corresponding to the agent's EnvVar definition. This method immediately overrides the default path without modifying configuration files.

export AGENTSVIEW_DATA_DIR=$HOME/.agentsview          # Optional global root

export CLAUDE_PROJECTS_DIR=$HOME/my-claude-sessions   # Per-agent override

agentsview serve

As implemented in internal/config/config.go (lines 88‑94), the application replaces the default directory slice with the value of the matching environment variable. When CLAUDE_PROJECTS_DIR is set, agentsview reads sessions from your custom path instead of the default $HOME/.claude/projects.

Method 2: TOML Configuration for Multiple Directories

To specify multiple search directories for an agent, use the TOML key defined in the ConfigKey field. Create or edit $AGENTSVIEW_DATA_DIR/config.toml:

# Per-agent directory overrides

claude_project_dirs = ["/data/claude1", "/data/claude2"]
codex_sessions_dirs = ["/data/codex", "/backup/codex-sessions"]

According to the parsing logic in internal/config/config.go (lines 78‑84), the configuration loader reads these arrays into Config.AgentDirs[agent]. The sync engine searches these paths in order when locating session files. This method is particularly useful for unsupported agents that require multiple session sources or specialized directory structures.

Method 3: Global Data Directory Relocation

To change the storage location for all agents, databases, and internal files simultaneously, set the AGENTSVIEW_DATA_DIR environment variable (or the legacy AGENT_VIEWER_DATA_DIR):

export AGENTSVIEW_DATA_DIR=/mnt/agentsview-data
agentsview serve

This relocates the entire data root, including sessions.db, config.toml, and default agent subdirectories, to the specified path. The global data directory resolution occurs in internal/config/config.go (lines 78‑86).

Configuration Precedence Rules

Understanding the override hierarchy is critical when you configure custom session directories for unsupported agents:

1. Defaults - Hardcoded paths from internal/parser/types.go
2. Config File - Values from $AGENTSVIEW_DATA_DIR/config.toml
3. Environment Variables - Runtime env vars (highest priority for per-agent settings)
4. CLI Flags - Command-line arguments (final override)

Important: Environment variables take precedence over TOML configuration. If CODEX_SESSIONS_DIR is set in the environment, any codex_sessions_dirs entries in config.toml are ignored. This behavior is enforced during the loadEnv phase in internal/config/config.go.

Summary

• Environment variables provide single-directory overrides via the EnvVar field defined in internal/parser/types.go (lines 46‑55)
• TOML configuration supports multiple directories through ConfigKey arrays parsed in internal/config/config.go (lines 78‑84)
• Global relocation uses AGENTSVIEW_DATA_DIR to move all data, as implemented in internal/config/config.go (lines 78‑86)
• Precedence follows: defaults → config file → environment → CLI flags
• Restart required - You must restart the agentsview server after any configuration change for the overrides to take effect

Frequently Asked Questions

How do I configure directories for a completely unsupported agent?

To configure custom session directories for unsupported agents not defined in internal/parser/types.go, add custom entries to your config.toml file using the appropriate agent identifier as the configuration key. While unsupported agents won't have predefined EnvVar constants in the source code, you can still define directory arrays in TOML. For complete support, you may need to add a new AgentDef entry to internal/parser/types.go with the appropriate EnvVar and ConfigKey fields, then recompile.

Why are my TOML configuration changes being ignored?

Your environment variables are overriding the TOML settings. As implemented in internal/config/config.go (lines 88‑94), environment variables take precedence over configuration file entries. Check for conflicting variables like CLAUDE_PROJECTS_DIR or CODEX_SESSIONS_DIR in your shell environment using env | grep DIR, and unset them to allow the TOML values to take effect.

Can I use relative paths when configuring custom directories?

While agentsview accepts relative paths, absolute paths are strongly recommended when you configure custom session directories for unsupported agents. Relative paths are resolved against the working directory where agentsview serve is executed, which can cause inconsistencies if the service runs under different user contexts or systemd services.

What is the difference between AGENTSVIEW_DATA_DIR and agent-specific overrides?

AGENTSVIEW_DATA_DIR sets the global root for all agentsview internal data, including the SQLite database, cache files, and the config.toml file itself, as defined in internal/config/config.go (lines 78‑86). Agent-specific directories (set via EnvVar or ConfigKey) only override where session files are read for that particular agent, while the database and other internal files remain under the global data directory.

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