How to Configure Custom Agent Session Directories in agentsview

You can configure custom agent session directories in agentsview using environment variables for single-directory overrides, TOML configuration arrays for multiple directories, or by changing the global AGENTSVIEW_DATA_DIR to relocate all application data.

agentsview stores session files for each supported AI agent under a configurable data directory structure. By default, the application looks for sessions in per-agent subdirectories, but you can override these locations to support custom workflows, multiple project roots, or external storage systems. This guide leverages the actual source code from the kenn-io/agentsview repository to show you exactly how these mechanisms work.

Understanding the Configuration Hierarchy

According to the source code in internal/config/config.go, agentsview loads configuration in a strict order: defaults first, then the TOML configuration file, followed by environment variables, and finally CLI flags. The final directory list for each agent is stored in Config.AgentDirs[agent] and used by the sync engine and file-watcher. This hierarchy means that environment variables always win over configuration file settings.

Method 1: Environment Variables for Single-Directory Overrides

Environment variables provide the highest precedence for configuring individual agent directories. In internal/parser/types.go (lines 46-55), each agent definition includes an EnvVar field that maps to a specific environment variable name.

When the loadEnv function runs in internal/config/config.go (lines 88-94), it replaces the default directory slices with the value of the matching environment variable. This method supports only a single directory per agent.

export CLAUDE_PROJECTS_DIR=/my/custom/claude/projects
export CODEX_SESSIONS_DIR=/my/codex/sessions
agentsview serve

Method 2: TOML Configuration for Multiple Directories

To specify multiple directories for a single agent, use the TOML configuration file. The mapping between configuration keys and agents is defined in the ConfigKey field of internal/parser/types.go (lines 46-55).

The file-parsing logic in internal/config/config.go (lines 78-84) reads these keys as arrays. Create or edit $AGENTSVIEW_DATA_DIR/config.toml:

claude_project_dirs = ["/data/claude/work", "/data/claude/personal"]
codex_sessions_dirs = ["/data/codex", "/backup/codex"]

If an environment variable is set for an agent, the TOML values are ignored for that specific agent.

Method 3: Global Data Directory

To change the location of all agentsview data—including the database, settings, and session files—set the AGENTSVIEW_DATA_DIR environment variable. This is processed in internal/config/config.go (lines 78-86). The legacy variable AGENT_VIEWER_DATA_DIR is also supported for backwards compatibility.

export AGENTSVIEW_DATA_DIR=/mnt/agentsview-data
agentsview serve

This relocates sessions.db, config.toml, and all agent subdirectories to the specified path.

Complete Configuration Examples

Override a Single Agent via Environment Variable

export AGENTSVIEW_DATA_DIR=$HOME/.agentsview
export CLAUDE_PROJECTS_DIR=$HOME/my-claude-sessions
agentsview serve

Claude sessions will be read from $HOME/my-claude-sessions instead of the default $HOME/.claude/projects.

Provide Multiple Directories via config.toml

Create $HOME/.agentsview/config.toml:

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

Restart agentsview to search these paths in order for session files.

Combine Environment and Config File

export CODEX_SESSIONS_DIR=/my/codex
agentsview serve

Even if codex_sessions_dirs is defined in config.toml, Codex will only use /my/codex because the environment variable takes precedence.

Change the Global Data Directory

export AGENTSVIEW_DATA_DIR=/mnt/agentsview-data
agentsview serve

All internal files are now stored under /mnt/agentsview-data.

Summary

• Environment variables (e.g., CLAUDE_PROJECTS_DIR) override single agent directories and take precedence over all other methods, as implemented in internal/config/config.go lines 88-94.
• TOML configuration supports multiple directories per agent via array syntax (e.g., claude_project_dirs = ["/path1", "/path2"]), parsed in internal/config/config.go lines 78-84.
• Global data directory (AGENTSVIEW_DATA_DIR) relocates the entire application data root, including the config file and database.
• Configuration loads in the order: defaults → config file → environment → CLI flags.
• Restart the server after any configuration change for it to take effect.

Frequently Asked Questions

Can I use both environment variables and the config.toml file together?

Yes, but environment variables take precedence. If you set CLAUDE_PROJECTS_DIR in your shell, any claude_project_dirs entries in config.toml are ignored according to the loading logic in internal/config/config.go. Use environment variables for temporary overrides and TOML for persistent multi-directory configurations.

Where does agentsview store its configuration file?

By default, agentsview looks for config.toml inside the directory specified by AGENTSVIEW_DATA_DIR. If unset, this defaults to a system-specific user data directory (typically $HOME/.agentsview on Unix systems). You can verify the exact path by checking the startup logs or setting AGENTSVIEW_DATA_DIR explicitly.

How do I configure multiple directories for a single agent?

Use the TOML configuration file with array syntax. For example, set claude_project_dirs = ["/work/projects", "/personal/projects"] in your config.toml. Environment variables only support single directory values, as defined in the AgentDef struct in internal/parser/types.go.

Why is my config.toml change not taking effect?

Ensure you have restarted the agentsview server after saving the file. Also, verify that no environment variable is overriding the specific agent configuration, as environment variables take precedence over TOML settings according to the hierarchy in internal/config/config.go.

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