theam / theam/facility

init misreports the failed .agents/skills symlink on Windows (EPERM, not a filesystem limitation); a junction would work

Open Beginner friendly
#230 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
71
Forks
64
Avg merge
15h 38m
Merged PRs (30d)
66

Description

Summary

On Windows, init prints

! .agents/skills symlink could not be created (filesystem without symlink support) — skipped.

The filesystem supports symlinks; what fails is symlinkSync(..., "dir") with EPERM, because Windows only grants SeCreateSymbolicLinkPrivilege to administrators or with Developer Mode on. A directory junction needs no privilege and works for this purpose:

> node -e "fs.symlinkSync('../.claude/skills','.agents/skills','dir')"
code: EPERM | EPERM: operation not permitted, symlink '..\.claude\skills' -> '...\.agents\skills'
> node -e "fs.symlinkSync('../.claude/skills','.agents/skills','junction')"
junction OK

Where

src/init.mjs:513-519 catches every error from symlinkSync and reports the same message.

Why it matters

.agents/skills is how non-Claude tooling discovers the vendored skills (init.mjs:507, concepts/method.md:153, validate-delivery-loop.md:186), so on a Windows workstation the Codex lane runs without them and the warning points the user at the wrong cause.

Fix

On EPERM, retry with type: "junction" (Node resolves the target to an absolute path for junctions, which is fine here); if that fails too, print the actual error code instead of guessing. One-line change plus a test that asserts either a symlink or a junction exists after init on win32. Happy to open the PR.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at src/init.mjs:507-519 and review the existing init behavior and error handling around .agents/skills. Verify the Windows path with the supplied symlink and junction commands, then add the requested test so init passes when either a symlink or junction exists and reports the actual error when both fail.

Written by the indexing model from the issue text.

Assessment

Tech stack
node.js
Domain
cli, tooling
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
84/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.