Configuration

cargo agents uses a single user-wide configuration file at ~/.symposium/config.toml. Created by cargo agents init.

Full example

auto-sync = true
agents-syncing = true
hook-scope = "global"
auto-update = "on"

[[agent]]
name = "claude"

[[agent]]
name = "gemini"

[logging]
level = "info"

[defaults]
symposium-recommendations = true
user-plugins = true

[[plugin-source]]
name = "my-org"
git = "https://github.com/my-org/symposium-plugins"

[[plugin-source]]
name = "local-dev"
path = "my-plugins"

Top-level keys

Agents syncing: mirror user-authored skills

Agents such as Copilot, Gemini, Codex, Goose, and OpenCode all read skills from the vendor-neutral .agents/skills/ directory, but Claude Code and Kiro use their own paths (.claude/skills/ and .kiro/skills/). When agents-syncing is enabled, every workspace plugin — the workspace root and each member directory — carries a second default skill group, gated by the workspace-member() predicate:

[[skills]]
predicates = ["workspace-member()"]
source.path = ".agents/skills"

Skills you author in .agents/skills/ therefore flow through the same pipeline as every other skill and install into each configured agent’s own skill directory, so a single authored copy is visible to every agent. The workspace-member() gate is what keeps these maintainer skills from installing for dependents of a published crate — they apply only while working in the workspace itself.

Two .symposium-marker rules keep sources and copies distinct (symposium never writes a marker into a source, only into directories it installs):

• Skill discovery skips marker-bearing directories, so copies symposium installed into .agents/skills/ (for agents that read it natively) are never re-discovered as sources.
• For an agent whose skill directory is .agents/skills/, a skill whose source already sits at its install slot is left in place — nothing is copied.

Installed copies receive the same marker and * .gitignore that plugin-installed skills get, which means: updates to the source are re-copied on each sync; removing the source removes the copies on the next sync (the normal stale-skill reap); disabling agents-syncing = false does the same; and a pre-existing user-managed directory in a target is never overwritten (the skill installs under a suffixed name instead).

Because these are real skills now, SKILL.md frontmatter must carry name and description like any other skill definition.

Hook scope: control whether Symposium activates in all projects or only those you select

Registering hooks globally ensures that Symposium activates whenever you use the selected agent, which means that it will work in any Rust project automatically.

Registering hooks at the project level requires you to run cargo agents sync within each project at least once to create the hooks. After that, the auto-sync feature will keep you up-to-date.

[[agent]]

Each [[agent]] entry identifies an agent you use. You can configure multiple agents.

[logging]

[telemetry]

Opt-in, per-user usage telemetry. Off by default. When enabled, Symposium appends anonymous events as JSON lines to a local, per-day log under ~/.symposium/telemetry/. Nothing is uploaded automatically — you inspect and share the data yourself with cargo agents telemetry show. The preference is also collected during cargo agents init. See the telemetry design chapter for the event format.

[telemetry]
enabled = true

[defaults]

Controls the two built-in plugin sources. Both are enabled by default.

[[plugin-source]]

Defines additional plugin sources. Each entry must have exactly one of git or path.

Directory resolution

User-wide data lives under ~/.symposium/ by default. Override with environment variables:

SYMPOSIUM_HOME takes precedence over XDG variables.

File locations