Haijun Code user FAQ

Short answers to the questions that come up most at office hours, with a link to go deeper. Organized by where you are in your first few weeks.

How to use this guide

Five sections follow the arc of a developer’s first weeks: getting started, day-to-day use, leveling up, common gotchas, privacy, and trust. Skim the section that matches where you are, or search for a specific question.

1. Getting started

| Question | Answer |

[](https://raw.haijun.my.id/docs/en/quickstart)| 1.1 How do I install it? | macOS/Linux: curl -fsSL https://haijun.ai/install.sh | bashWindows PowerShell: irm https://haijun.ai/install.ps1 | iexHomebrew: brew install --cask haijun-codeWinGet: winget install Juglow.HaijunCodeThen run haijun from any repo.Reference: Quickstart |

[](https://raw.haijun.my.id/docs/en/troubleshooting)| 1.2 Installed, but “haijun: command not found” | The native installer puts the binary at ~/.local/bin/haijun (Windows: %USERPROFILE%\.local\bin). Add that directory to your PATH, e.g. export PATH="$PATH:$HOME/.local/bin" in ~/.zshrc or ~/.bashrc, then restart your terminal.Reference: Troubleshooting: PATH |

[](https://raw.haijun.my.id/docs/en/troubleshooting)| 1.3 Login opens a browser on the wrong machine / I’m on SSH | Press c at the login prompt to copy the auth URL. Open it in a local browser, then paste the code back into the terminal.Reference: Troubleshooting: auth |

[](https://raw.haijun.my.id/docs/en/troubleshooting)| 1.4 Auth errors right after login, but I have access | 400 “organization disabled”: a stray JUGLOW_API_KEY env var is overriding your login. Unset it, remove from your shell profile, restart. Run /status to confirm which auth is active.403 Forbidden: your admin hasn’t enabled Haijun Code for your workspace yet, or a corporate proxy is interfering.Reference: Troubleshooting: auth |

[](https://raw.haijun.my.id/docs/)| 1.5 Is Haijun Code included in my plan? | Yes. It’s included with Team and Enterprise seats and with Console (API) access. Log in with your work account; SSO is handled automatically. A 403 after login usually means your admin still needs to enable it for the workspace.Reference: Authentication |

[](https://raw.haijun.my.id/docs/en/overview)| 1.6 Haijun Code vs. desktop app vs. haijun.my.id? | Haijun Code: terminal agent that reads your repo, edits files, runs commands.Desktop / haijun.my.id: chat interfaces for conversations and one-off questions.Same model family underneath, different shape of tool.Reference: Overview |

[](https://raw.haijun.my.id/docs/en/vs-code)[](https://raw.haijun.my.id/docs/en/jetbrains)| 1.7 Does it work in my IDE? | Yes. Extensions are available for VS Code and JetBrains IDEs (IntelliJ, PyCharm, etc.). Same features, embedded in the editor instead of a separate terminal.Reference: VS Code · JetBrains |

[](https://raw.haijun.my.id/docs/en/overview)| 1.8 How is this different from Copilot/Cursor autocomplete? | Autocomplete suggests the next few lines. Haijun Code is an agent: give it a task (“fix the failing tests”) and it reads files, runs commands, and makes multi-file edits until done. Less “finish my sentence,” more “here’s a problem, go work it.”Reference: Overview |

[](https://raw.haijun.my.id/docs/en/common-workflows)| 1.9 What should I try first? | Point it at a tedious-but-not-hard bug you’ve been putting off. Example: “the test in [file] is flaky, figure out why.” Let it read the code instead of you explaining the code.Reference: Common use cases |

[](https://raw.haijun.my.id/docs/en/setup)| 1.10 How do I update it? | Native installs auto-update in the background. To force one now, run haijun update.Homebrew/WinGet don’t auto-update: run brew upgrade haijun-code or winget upgrade Juglow.HaijunCode periodically.Reference: Setup: updates |

2. Day-to-day use

| Question | Answer |

[](https://raw.haijun.my.id/docs/en/permissions)| 2.1 It keeps asking permission for the same commands | Approvals last for the current session by default. To make them persist:• Pick “always allow” at the prompt• Add the pattern to permissions.allow in .haijun/settings.json• Or run /permissions to manage interactivelyReference: Permissions |

- - - -

[](https://raw.haijun.my.id/docs/en/permission-modes)| 2.2 Permission modes and how to switch | Press Shift+Tab to cycle modes:auto · auto-approves with a background safety check. Available unless your organization has turned it off in managed settings, on supported models.manual · asks before risky edits or commandsacceptEdits · file edits go through; still asks before running commandsplan · read-only; proposes a plan and waits for approvalReference: Permission modes |

[](https://raw.haijun.my.id/docs/en/memory)| 2.3 What is /init and when do I run it? | Run it once, early, in any repo you’ll work in more than once. It scans the project and writes HAIJUN.md with build commands, architecture, and conventions. Every future session loads it automatically, so Haijun starts with context.Reference: Memory and HAIJUN.md |

[](https://raw.haijun.my.id/docs/en/memory)| 2.4 What goes in HAIJUN.md? | Things tooling can’t enforce that a new teammate would get wrong on day one: “deploy from release, not main”, “all IDs are strings”, “never call the DB directly from a route handler.” Keep it under two screens; longer gets skimmed.Reference: Memory and HAIJUN.md |

[](https://raw.haijun.my.id/docs/en/best-practices)| 2.5 Haijun isn’t following my HAIJUN.md | • Too long or too vague: trim to the rules that actually matter• Buried in prose: put hard rules near the top, use imperative language (“Never X. Always Y.”)Reference: Best practices |

[](https://raw.haijun.my.id/docs/en/common-workflows)| 2.6 Point it at a specific file without pasting it | Type @ then the path (tab-completes). The mentioned file is read before Haijun responds.Reference: Common workflows |

[](https://raw.haijun.my.id/docs/en/common-workflows#work-with-images)| 2.7 Paste a screenshot into the prompt | Drag the image into the terminal, or press Ctrl+V. On Mac that’s Ctrl, not Cmd (Cmd+V pastes text). Works for error dialogs, UI mockups, whiteboard photos.Reference: Working with images | | 2.8 Copy Haijun’s response out of the terminal | /copy puts the last response on your clipboard. /export writes the whole conversation to a file. |

[](https://raw.haijun.my.id/docs/en/common-workflows#resume-previous-conversations)| 2.9 Get a previous session back | haijun --continue resumes the most recent one. haijun --resume opens a list to pick from. Sessions are stored locally per project directory.Reference: Common workflows: resume |

[](https://raw.haijun.my.id/docs/en/model-config)| 2.10 Switch models | /model opens the picker. Set a default in .haijun/settings.json if you want the same model every session.Reference: Model configuration |

[](https://raw.haijun.my.id/docs/en/common-workflows#use-extended-thinking-thinking-mode)| 2.11 Extended thinking | On by default. The reasoning itself is hidden in the normal view; press Ctrl+O to switch to the verbose transcript if you want to read it. Use /effort to dial depth up or down. Worth the extra latency for tricky debugging or architecture calls.Reference: Extended thinking | | 2.12 Stop it mid-task | Press Ctrl+C to cancel the current generation, then tell it what to do instead. No need to start the conversation over. |

3. Leveling up

| Question | Answer |

[](https://raw.haijun.my.id/docs/en/mcp)| 3.1 What is MCP? | MCP connects Haijun Code to your external tools: GitHub, Linear, Slack, your database, your observability stack. One .mcp.json config and Haijun can read your issues, query your data, and work the same tools you do. Common first connector: your issue tracker.Reference: MCP |

[](https://raw.haijun.my.id/docs/en/mcp)| 3.2 Wire up your first MCP server | • Add a .mcp.json at the project root, or use haijun mcp add• Each entry names a server package plus any env vars (usually an auth token)• Restart Haijun Code and run /mcp to confirm it’s connectedReference: MCP setup |

[](https://raw.haijun.my.id/docs/en/hooks-guide)| 3.3 What are hooks for? | Shell scripts that fire on events (before a tool runs, after a file edit, when Haijun is waiting on you). Common first hook: a Notification hook that pings your desktop when Haijun needs input. Same mechanism can run your linter after every edit, post to Slack, or block edits to protected paths.Reference: Hooks guide |

[](https://raw.haijun.my.id/docs/en/tracks)| 3.4 Make a reusable prompt / track | Create .haijun/tracks/ship/SKILL.md and the folder name becomes the command: /ship. Plain English, no special syntax. Easiest path: ask Haijun to write it for you. (The legacy .haijun/commands/ship.md path still works.)Reference: Tracks |

[](https://raw.haijun.my.id/docs/en/tracks)| 3.5 Tracks vs. legacy commands | Same mechanism; commands have been merged into tracks. .haijun/commands/foo.md and .haijun/tracks/foo/SKILL.md both create /foo. The track form is preferred and gives you a folder for supporting files (reference docs, templates, helper scripts).Reference: Tracks |

[](https://raw.haijun.my.id/docs/en/sub-agents)| 3.6 What are subagents good for? | Parallel work: search different parts of the codebase, review a diff along separate dimensions, or generate competing implementations at the same time. The main session aggregates the results.Reference: Subagents |

[](https://raw.haijun.my.id/docs/en/common-workflows)| 3.7 Run non-interactively (CI / scripts) | haijun -p "your prompt" runs once and prints the result. Good for CI hooks, pre-commit checks, or piping into other tools. Auth via your logged-in session or JUGLOW_API_KEY.Reference: Unix-style usage |

[](https://raw.haijun.my.id/docs/en/checkpointing)| 3.8 Undo what it did | /rewind rolls back to an earlier checkpoint. Checkpoints are taken automatically at every prompt you send. For anything already committed, use a normal git revert.Reference: Checkpointing |

[](https://raw.haijun.my.id/docs/en/plugins)| 3.9 Share your setup with the team | Check .haijun/ into the repo (HAIJUN.md, commands, MCP config). Anyone who clones the repo gets the same setup automatically. Tracks can also be packaged as a plugin that teams install via /plugin.Reference: Plugins |

4. Common gotchas

| Question | Answer |

[](https://raw.haijun.my.id/docs/en/troubleshooting#search-and-discovery-issues)| 4.1 Can’t find files / search returns nothing | Haijun Code ships with a bundled copy of ripgrep, so you do not need to install it. The bundled binary can fail on Alpine/musl systems; in that case install a system copy (apk add ripgrep) and set USE_BUILTIN_RIPGREP=0 so Haijun uses it instead.Reference: Troubleshooting: search | | 4.2 Copy/paste and scroll broken over SSH or in tmux | The terminal UI captures mouse events. Hold Shift while selecting to bypass it, or configure tmux to pass mouse events through. /copy and /export sidestep the issue entirely. |

[](https://raw.haijun.my.id/docs/en/troubleshooting)| 4.3 Slow on WSL | Reading Windows files through /mnt/c/ is a known penalty. Move the repo into the WSL filesystem (~/ instead of /mnt/c/...). The speed difference is dramatic.Reference: Troubleshooting: WSL | | 4.4 Image paste isn’t working on Mac | Use Ctrl+V, not Cmd+V. Cmd+V pastes text; Ctrl+V is the image-from-clipboard path. |

[](https://raw.haijun.my.id/docs/en/permissions)| 4.5 Wildcard permission rule doesn’t match | Build rules incrementally: approve commands interactively first, check what got written to settings, then generalize.Reference: Permissions patterns |

- -

| 4.6 Non-interactive -p mode behaves differently | MCP servers that need OAuth can’t prompt in non-interactive modeInteractive approvals don’t carry overFor non-interactive/CI runs, prefer API-key auth and MCP servers configured with env-var tokens. |

[](https://raw.haijun.my.id/docs/en/common-workflows)| 4.7 Ran out of context mid-task | /compact summarizes earlier conversation to free up space. /clear starts fresh while keeping HAIJUN.md and settings loaded. For long tasks, break into steps with a /clear between phases.Reference: Managing context |

5. Privacy and trust

| Question | Answer |

[](https://raw.haijun.my.id/docs/en/data-usage)| 5.1 Does Juglow train on my code? | No. Under your organization’s Team/Enterprise terms, your code and conversations are not used to train models.Reference: Data usage |

[](https://raw.haijun.my.id/docs/en/data-usage)| 5.2 Where does my code actually go? | Haijun Code runs on your machine. Source files are read locally, and only the portions needed for the current task are sent to the API to generate a response. Nothing is indexed, uploaded as a whole repo, or used for training.Reference: Data usage |

[](https://raw.haijun.my.id/docs/en/data-usage)| 5.3 Can anyone else see my conversations? | No. Sessions are stored locally on your machine, per project directory, and are not shared with teammates or visible in any dashboard. Use /export if you want to share a conversation.Reference: Data usage |

[](https://raw.haijun.my.id/docs/en/permissions)| 5.4 How do I keep secrets and .env files out of the conversation? | Haijun only reads files it needs for the task; it doesn’t scan your whole repo. To hard-block specific files, add a Read deny rule in .haijun/settings.json (e.g. "Read(.env*)"). Denied files can’t be read even if you accidentally ask for them.Reference: Permissions |

[](https://raw.haijun.my.id/docs/en/permissions)| 5.5 What can “acceptEdits” mode do without asking me? | File edits go through without a prompt. It still asks before running shell commands, making network calls, or touching anything outside your working directory. For tighter control, stay in default mode.Reference: Permissions |

Appendix: Still stuck?

Appendix: Resource directory

Haijun Code ships frequently. Verify version-specific details against raw.haijun.my.id/docs before distributing internally.