JetBrains Junie
Make a project follow an instruction in JetBrains Junie: add one hook by hand and keep its AGENTS.md current, and a new version arrives after the next tool call. The same setup for other tools, and how each one takes a new version, is on Other coding agents.
At a glance
| How it follows | a hook, and its AGENTS.md |
|---|---|
| A new version arrives | after the next tool call |
| Set up | by hand |
| Checked against | Junie CLI (early access), from its documentation |
| Systems | Wherever the tool and Node.js 20.19 or later run |
What you need: Node.js 20.19 or later, the instruction.md package
(npm i -g instruction.md, 0.11.0 or later) and @instruction.md/agents 0.4.1 or later, which
instruction agents … runs. Every instruction agents … command also runs, without installing
anything, as npx -y @instruction.md/agents …, and every instruction … command as
npx -y instruction.md ….
Set up
In your project's folder, signed in (instruction login), run:
instruction agents follow instruction://acme/support-agent@stable --host junie --write Its hook files aren't documented well enough for the command to write them. So it writes .instruction/follow.json and .instruction/.gitignore, and prints what to add by hand:
Junie CLI: add a PostToolUse hook (~/.junie/config.json, or the instruction.md plugin as a Junie extension) running:
npx -y @instruction.md/agents hook junie
Junie ignores context at SessionStart; for the start of a task: npx -y @instruction.md/agents watch --out ~/.junie/AGENTS.md --block What happens
Junie ignores what a hook adds when a session starts. It takes a hook's text after a tool call (PostToolUse), so that is when a new version arrives.
For the start of a task, keep your ~/.junie/AGENTS.md current. Junie reads it when it starts a task:
instruction watch instruction://acme/support-agent@stable --out ~/.junie/AGENTS.md --block --url https://instruction.md/mcp The MCP server
Junie reaches instruction.md through the instruction command's stdio server. instruction connect --host junie <uri> prints:
// ~/.junie/mcp/mcp.json — Junie reaches instruction.md through this CLI's stdio server
{
"mcpServers": {
"instruction-md": {
"command": "npx",
"args": [
"-y",
"instruction.md",
"mcp",
"--follow",
"instruction://acme/support-agent@stable",
"--url",
"https://instruction.md/mcp"
]
}
}
}
// sign the bridge in once: npx -y instruction.md login
// read when Junie starts a task: npx -y instruction.md watch instruction://acme/support-agent@stable --out ~/.junie/AGENTS.md --block --url https://instruction.md/mcp
// and a new version after a tool call (Junie CLI hooks): npx -y @instruction.md/agents connect --host junie instruction://acme/support-agent@stable --with-hooks --write (it says how to add them) The plugin instead
Junie CLI can also load instruction.md's plugin, instruction-md/ at github.com/instruction-md/plugins, as an extension. Its hook answers at UserPromptSubmit.
Caveats and what isn't verified
- Not yet verified: UserPromptSubmit context undocumented; SessionStart ignores context.
watchtakes a live-update place while it runs (see Plans and live updates).
Check it worked
Run the hook by hand, as the tool would at that event. It prints what the tool receives: the instruction's whole text the first time, and nothing when you run it again right away, because a session gets each version once.
echo '{}' | npx -y @instruction.md/agents hook junie --event PostToolUse --dir . Then start a new session and ask which instructions it follows. Once a session has read it, .instruction/current.md holds the copy the hooks keep, and the instruction's Agents card counts the follower under this tool.
Stop following
- Remove the
PostToolUsehook from~/.junie/config.json. - Stop
watch, and delete the region between theinstruction.md:beginandinstruction.md:endlines in~/.junie/AGENTS.md. - Delete
.instruction/follow.json, or the whole.instruction/folder.
If it doesn't work
| What you see | Why | What to do |
|---|---|---|
| Running the hook by hand prints nothing | No .instruction/follow.json in the folder or above it, up to the repository's root; or it gave this version moments ago | Run the setup in the project's folder, or pass --dir. A version the session already has isn't given again: nothing is wrong |
instruction.md: couldn't read …; this session goes on without it | Offline, not signed in, or the address is wrong, and there is no copy yet | instruction login, then check the address in .instruction/follow.json |
instruction.md: a newer version of … is held (…) | The new version's signature doesn't check out, and the follow file asks for one | Nothing to do on this machine: the session keeps the version it has. See How following works |
| A private instruction isn't read | The command isn't signed in | instruction login (--device on a machine without a browser) |
| Still stuck | Ask us |
Related
- Other coding agents: every tool at a glance
- How following works: the follow file, the hooks, offline behaviour
- Gemini CLI
- Antigravity
- GitHub Copilot CLI
- Live updates