Skip to main content

Open a folder

Knox Agent is a workspace agent. Open the project with File → Open Folder… (or a .code-workspace with folders). Until a folder is open, tools have no tree to read or edit.

Primary root​

In a single-folder window, that folder is the root.

In a multi-root workspace, the folder of the active editor file is the primary root. Shell commands, git, builds, and relative paths run there. Search, glob, instruction files, hooks, and custom agents still cover all roots. Nested .knoxignore is honored. Checkpoints are stored per folder.

If you keep jumping between two repos in one window, watch which file is focused before you let Auto run the shell.

Two places files live​

On this machine — ~/.knoxcoder​

Global Knox state (override the whole path with KNOX_GLOBAL_DIR):

PathContents
config.yamlModels, providers, some agent config
auth.jsonKnox OAuth session, mode 0600
sessions/Chat transcripts
Memory Brain sqliteFacts, graph, recipes (if enabled)
checkpointsByte-exact snapshots, not git
skills/, prompts, logs, job outputUser-level extras

This directory is not ~/.knox. Marketplace Knox (knoxchat.knoxchat) owns ~/.knox. KnoxCoder never migrates that folder. Copy files by hand if you want them.

On Windows: C:\Users\<you>\.knoxcoder.

In the repo — .knoxcoder/ and friends​

These are project files you can commit:

PathRole
AGENTS.mdProject instructions (also .knoxcoder/AGENTS.md, nested AGENTS.md closer to the open file, CLAUDE.md, .knoxrules)
.knoxcoder/hooks.jsonLifecycle hooks
.knoxcoder/agents/*.mdCustom subagents
.knoxcoder/promptsExtra slash commands
skills/ or skill/Project skills (SKILL.md)
.knoxignoreCheckpoint / scan ignore (repo + a global one under ~/.knoxcoder)
.knoxcoder/config.yamlOptional project config

Never create .knox/ in a KnoxCoder project. That name belongs to the marketplace extension.

Type /instructions to list everything loaded, in order, with token cost. Warnings fire if a single file is over 2000 tokens or always-on instruction text is over 6000. /init writes a starter AGENTS.md (refuses to overwrite without --force).

Opt-in extras, off unless you set them: knoxchat.compatInstructions = cursor (.cursor/rules, .cursorrules) and/or copilot (.github/copilot-instructions.md). They sit below AGENTS.md.

Git remotes and first-session mode​

A fresh clone (no prior Knox sessions for that folder, remote not in knoxchat.trustedGitRemotes) starts the permission bar in Ask. After Knox has used the folder, or if the remote substring is allowlisted, new sessions start in Auto. knoxchat.permissionDefault overrides the heuristic; a saved mode for the folder still wins.

See First chat for Ask / Edits / Auto.

What Knox will not use as a workspace​

  • Remote SSH, WSL, Dev Containers — not supported for the Knox host in 2.2. Open the files on the machine where KnoxCoder is running.
  • Virtual documents / untitled files only — open a folder if you want edits, checkpoints, and git tools.
  • No git repo — chat and file tools still work. Git tools (builtin_git_status, commit, …) fail immediately instead of hanging. Checkpoints do not need git.

Disable Knox for this window​

Extensions view → Knox → Disable. It cannot be uninstalled. Disabling hides the sidebar and commands; ~/.knoxcoder stays on disk.

To stop Memory Brain in this folder only, set knoxchat.memoryBrain.workspaceEnabled to false as a workspace setting. The global switch is knoxchat.memoryBrain.enabled (or KNOX_BRAIN_ENABLED=0).

Next​

First chat · AGENTS.md and rules · Memory Brain