Skip to main content
Version: v1.0

Troubleshooting

Start with the installed help and the read-only project diagnostic:

agentbriefer --version
agentbriefer --help
agentbriefer doctor

Command not found after installation​

Open a new terminal, then check the binary directory for your installation method.

npm prefix -g
echo "$HOME/.cargo/bin"

Add the applicable binary directory to PATH. On Windows, reopen PowerShell after the installer updates the environment.

No agentbriefer.yaml found​

Project commands resolve the current working directory. Change to the configured repository root or initialize the current directory:

cd path/to/project
agentbriefer init

YAML cannot be parsed​

Compare the file with the configuration schema. Common causes are incorrect indentation, a policy field placed outside project, or a list written as a scalar.

If the file is disposable, move it aside and rerun init; otherwise fix the YAML and run doctor.

Generated output is stale​

Refresh configured files and check again:

agentbriefer sync
agentbriefer doctor

If a file has no valid managed block, sync warns and replaces its contents. Back up valuable manual content first, establish the managed block, then restore the manual content outside the markers.

Manual output edits disappeared​

generate replaces a complete output. Only sync preserves text outside managed markers. Recover the previous file from source control, run sync to add a managed block, and keep restored notes outside it.

Agentbriefer will not write through an output path whose final file is a symbolic link. Replace it with a regular file in the project, then rerun the command. This boundary prevents an instruction path from redirecting writes somewhere unexpected.

Skill is unknown​

The project may reference an ID that is not bundled with the installed CLI version.

agentbriefer skill list
agentbriefer --version

Upgrade Agentbriefer if a teammate used a newer catalog. Otherwise correct or remove the invalid ID in agentbriefer.yaml, then run agentbriefer skill update.

Recommendations match when any compatible stack tag intersects detected language, framework, database, package manager, test tool, or dependency tags. Inspect before installing:

agentbriefer skill list --recommended
agentbriefer skill info <id>

Doctor reports warnings but exits successfully​

That is the v1 behavior: findings are diagnostic and do not set a failing exit code. Review the output explicitly in CI rather than treating process success as a clean report.

Still blocked​

Collect the output of agentbriefer --version, the relevant command, and a redacted configuration, then open a GitHub issue. Never include secrets or private skill content in a public report.