Project slash commands are invisible when .claude/commands/*.md are symlinks

[Johannes-Berggren]

Summary

bb's slash-command typeahead shows no project commands when .claude/commands/*.md are symlinks. The host-daemon command scanner skips every symlinked directory entry, so a repo that symlinks its commands into a shared location gets an empty "project commands" section, while Claude Code's own CLI loads them fine.

Where

host-daemon src/command-discovery.ts, walkMarkdownTree:

for (const entry of entries) {
  if (entry.isSymbolicLink()) {
    continue;
  }
  ...
}

Symlinks are followed only for user-origin skill roots:

function canFollowSkillSymlink(root: CommandScanRoot): boolean {
  return root.origin === "user" && root.source === "skill";
}

walkMarkdownTree backs the command shape (resolveCommandScanRoots -> <cwd>/.claude/commands, origin: "project"), so a project command that is a symlink is never discovered, in any shape.

Reproduce

1. In a project, mkdir -p .agents/skills/foo && printf -- '---\ndescription: demo\n---\nhi\n' > .agents/skills/foo/SKILL.md
2. ln -s ../../.agents/skills/foo/SKILL.md .claude/commands/foo.md
3. Open the slash-command menu in bb (or GET /api/v1/projects/<id>/commands?provider=claude-code&environmentId=<env>).

Expected: foo listed under project commands.
Actual: absent. Replacing the symlink with a regular file makes it appear immediately, which isolates the cause to the symlink check rather than the path, the environment, or caching.

Impact

Sharing one instruction file between Claude Code and Codex via symlinks is a common monorepo layout (.claude/commands/x.md -> .agents/skills/x/SKILL.md keeps the two harnesses from drifting). In our repo all 14 project commands are invisible in bb for this reason; the only visible non-builtin command is a regular file in ~/.claude/commands/.

Suggested fix

For the command shape, resolve symlinked entries with fs.stat and accept them when the target is a regular file inside the root's boundary. The cycle and root-escape concerns that motivate the blanket skip apply to recursive directory traversal; a symlinked leaf .md can be followed safely with a boundary check. Alternatively, extend canFollowSkillSymlink to project roots for file (non-directory) entries.

Version

bb 0.39.0, macOS (darwin 25.6.0), provider claude-code.

[Borjampm]

Same cause, second symptom: skill directories are dropped by the same rule, so
.claude/skills/x -> ../../.agents/skills/x is invisible for exactly the reason your
.claude/commands/*.md links are. Adding evidence rather than opening a duplicate.

Reproduced on main @ 8d926c3 (also packaged 0.40.0), macOS 26.4, Node v26.4.0,
claude 2.1.251 / codex 0.150.1 / pi 0.84.4.

Minimal A/B — one real directory, one in-repo symlink, same skills root:

mkdir -p repo/.claude/skills/h-real repo/.agents/skills/h-linked && git -C repo init -q .
printf -- '---\nname: h-real\ndescription: real\n---\n'     > repo/.claude/skills/h-real/SKILL.md
printf -- '---\nname: h-linked\ndescription: linked\n---\n' > repo/.agents/skills/h-linked/SKILL.md
ln -s ../../.agents/skills/h-linked repo/.claude/skills/h-linked

Claude Code CLI 2.1.251 :  h-linked, h-real
bb main @ 8d926c3       :  h-real

Three additions to what you documented:

1. It is not provider-specific. codex drops an entry link in .codex/skills and
pi in .pi/skills, identically. One rule, every provider.

2. Containment is not what is being enforced. I pointed a link at a sibling inside
the same skills directory — it cannot escape anything — and it is still dropped:

.claude/skills/e-real          (dir)              -> listed
.claude/skills/e-link-sibling  -> e-real          -> dropped
.claude/skills/e-link-abs      -> <abs>/e-real    -> dropped

3. The rule is inverted, not merely strict. While in-repo entry links are refused, a
non-recursive root link is followed straight out of the repository —
.claude/skills -> /outside loads everything under it. So today bb blocks the link that
cannot escape and follows the one that does. I filed that half separately as #2769 since it is
the opposite failure and lands independently.

The existing test that pins the current behavior only ever uses an outside target
(command-discovery.test.ts:501),
so the in-repository case looks unconsidered rather than deliberately refused — even
though PR #92 (27361799e) did intend "keep project-origin symlinked skills skipped".

On your suggested fix: it works, and it generalises. Replacing the origin check with
the containment check the docblock already describes fixes commands and skills from one
rule, reusing the boundaryPath that is already plumbed to every project root — no
contract or HOST_DAEMON_PROTOCOL_VERSION change. Following linked leaf files only,
and still skipping linked directories during the markdown walk, keeps your cycle and
escape concerns intact.

I have this implemented and tested against your repro shape and mine:

                                          main 8d926c3   with containment check
.claude/commands/deploy.md -> in-repo      (none)         deploy
.claude/commands/outside.md -> outside     (none)         (none)
.claude/skills/h-linked -> in-repo         h-real         h-linked, h-real
.claude/skills/c-link-out -> outside       c-real         c-real

Happy to open it as a PR against this issue if that is welcome — or to split the skills
half into its own issue if you would rather keep this one scoped to commands.

AGENT GENERATED