Documentation

Troubleshooting

pysar: command not found

  • Re-run the install script, or download a release binary.
  • Ensure the install directory is on PATH (~/.local/bin is common).
  • Check for a shadowing binary: which -a pysar and pysar --version.

Wrong or old version

Release installs often land in ~/.local/bin. A go install binary may land in $(go env GOPATH)/bin. Whichever directory appears first on PATH wins.

Host flags rejected together

--claude, --cursor, and --codex are mutually exclusive. Pass only one.

MCP server not connecting

  1. Confirm the pysar binary exists where the host config points (Cursor: ${userHome}/.local/bin/pysar; Claude/Codex: pysar on PATH).
  2. Claude: check project .mcp.json and that Claude Code loaded the server.
  3. Cursor: re-run pysar init --cursor (registers ~/.cursor/mcp.json), then reload MCP / restart Cursor. Confirm Customize → MCPs shows pysar, and project .cursor/mcp.json uses ${userHome}/.local/bin/pysar with PYSAR_PROJECT_ROOT=${workspaceFolder}.
  4. Codex: check .codex/config.toml for [mcp_servers.pysar], PYSAR_PROJECT_ROOT = ".", and default_tools_approval_mode = "approve".
  5. From the project directory, you can smoke-test the binary with pysar --help (stdio MCP is started by the host, not by a long-running daemon you manage yourself).

Codex keeps asking to allow pysar MCP tools

Shipped Codex config sets default_tools_approval_mode = "approve" (Codex skip-review dial for pysar MCP tools; auto is not enough when tools lack annotations). Refresh with:

pysar init --codex --force

Project .codex/config.toml applies only when Codex treats the project as trusted. If prompts continue after refresh, trust the project in Codex and retry. Untrusted projects may still prompt per tool.

Skills missing (/ps or $ps unknown)

Re-run init with --force for your host so global skills refresh:

pysar init --force # or pysar init --cursor --force pysar init --codex --force

Restart the host agent after skill install so it rediscovers skills (~/.claude/skills, Cursor plugin under Customize / ~/.cursor/plugins/local, or ~/.agents/skills for Codex).

Cursor keeps asking to approve MCP tools

Expected for now: Cursor scaffold does not include a Claude-style settings allowlist. Approve the pysar tools when prompted, or adjust Cursor’s MCP permissions for the project.

Piece files not appearing under .pysar/pieces/

  • Confirm the MCP server is connected for this workspace.
  • Skills must use MCP save tools — not manual writes into .pysar/.
  • Check the agent’s tool errors for save_*_bundle / path anchoring failures.

Draft or humanize save fails after /ps --research or --seo

Those flags persist piece preconditions. Draft save fails closed until research is full when --research was set; humanize save fails closed until seo.md exists when --seo was set. Finish the missing stage (or start a new piece without that flag) — do not skip past the gate.

Export missing or stale

  • Export needs at least a draft for the piece.
  • /ps exports at the end of a successful run; a stopped --review run may not have reached export yet.
  • Look under export_dir from .pysar/project (or the project root when unset); re-export overwrites the previous file for that piece at the same destination. Change the landing folder with pysar init --export-dir PATH or by editing export_dir — see Export.
  • Research [^shortname] markers in the exported file are expected until resolve-at-export ships; see Export. /ps --seo is not the cleanup for those markers.

Still stuck

Open an issue at github.com/malyshev/pysar with pysar --version, host (Claude Code, Cursor, or Codex), and the exact command or skill you ran.