@neocode-ai/web 1.1.1

package/src/content/docs/permissions.mdx

@@ -0,0 +1,237 @@
+---
+title: Permissions
+description: Control which actions require approval to run.
+---
+
+NeoCode uses the `permission` config to decide whether a given action should run automatically, prompt you, or be blocked.
+
+As of `v1.1.1`, the legacy `tools` boolean config is deprecated and has been merged into `permission`. The old `tools` config is still supported for backwards compatibility.
+
+---
+
+## Actions
+
+Each permission rule resolves to one of:
+
+- `"allow"` — run without approval
+- `"ask"` — prompt for approval
+- `"deny"` — block the action
+
+---
+
+## Configuration
+
+You can set permissions globally (with `*`), and override specific tools.
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "permission": {
+    "*": "ask",
+    "bash": "allow",
+    "edit": "deny"
+  }
+}
+```
+
+You can also set all permissions at once:
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "permission": "allow"
+}
+```
+
+---
+
+## Granular Rules (Object Syntax)
+
+For most permissions, you can use an object to apply different actions based on the tool input.
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "permission": {
+    "bash": {
+      "*": "ask",
+      "git *": "allow",
+      "npm *": "allow",
+      "rm *": "deny",
+      "grep *": "allow"
+    },
+    "edit": {
+      "*": "deny",
+      "packages/web/src/content/docs/*.mdx": "allow"
+    }
+  }
+}
+```
+
+Rules are evaluated by pattern match, with the **last matching rule winning**. A common pattern is to put the catch-all `"*"` rule first, and more specific rules after it.
+
+### Wildcards
+
+Permission patterns use simple wildcard matching:
+
+- `*` matches zero or more of any character
+- `?` matches exactly one character
+- All other characters match literally
+
+### Home Directory Expansion
+
+You can use `~` or `$HOME` at the start of a pattern to reference your home directory. This is particularly useful for [`external_directory`](#external-directories) rules.
+
+- `~/projects/*` -> `/Users/username/projects/*`
+- `$HOME/projects/*` -> `/Users/username/projects/*`
+- `~` -> `/Users/username`
+
+### External Directories
+
+Use `external_directory` to allow tool calls that touch paths outside the working directory where NeoCode was started. This applies to any tool that takes a path as input (for example `read`, `edit`, `list`, `glob`, `grep`, and many `bash` commands).
+
+Home expansion (like `~/...`) only affects how a pattern is written. It does not make an external path part of the current workspace, so paths outside the working directory must still be allowed via `external_directory`.
+
+For example, this allows access to everything under `~/projects/personal/`:
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "permission": {
+    "external_directory": {
+      "~/projects/personal/**": "allow"
+    }
+  }
+}
+```
+
+Any directory allowed here inherits the same defaults as the current workspace. Since [`read` defaults to `allow`](#defaults), reads are also allowed for entries under `external_directory` unless overridden. Add explicit rules when a tool should be restricted in these paths, such as blocking edits while keeping reads:
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "permission": {
+    "external_directory": {
+      "~/projects/personal/**": "allow"
+    },
+    "edit": {
+      "~/projects/personal/**": "deny"
+    }
+  }
+}
+```
+
+Keep the list focused on trusted paths, and layer extra allow or deny rules as needed for other tools (for example `bash`).
+
+---
+
+## Available Permissions
+
+NeoCode permissions are keyed by tool name, plus a couple of safety guards:
+
+- `read` — reading a file (matches the file path)
+- `edit` — all file modifications (covers `edit`, `write`, `patch`, `multiedit`)
+- `glob` — file globbing (matches the glob pattern)
+- `grep` — content search (matches the regex pattern)
+- `list` — listing files in a directory (matches the directory path)
+- `bash` — running shell commands (matches parsed commands like `git status --porcelain`)
+- `task` — launching subagents (matches the subagent type)
+- `skill` — loading a skill (matches the skill name)
+- `lsp` — running LSP queries (currently non-granular)
+- `todoread`, `todowrite` — reading/updating the todo list
+- `webfetch` — fetching a URL (matches the URL)
+- `websearch`, `codesearch` — web/code search (matches the query)
+- `external_directory` — triggered when a tool touches paths outside the project working directory
+- `doom_loop` — triggered when the same tool call repeats 3 times with identical input
+
+---
+
+## Defaults
+
+If you don’t specify anything, NeoCode starts from permissive defaults:
+
+- Most permissions default to `"allow"`.
+- `doom_loop` and `external_directory` default to `"ask"`.
+- `read` is `"allow"`, but `.env` files are denied by default:
+
+```json title="neocode.json"
+{
+  "permission": {
+    "read": {
+      "*": "allow",
+      "*.env": "deny",
+      "*.env.*": "deny",
+      "*.env.example": "allow"
+    }
+  }
+}
+```
+
+---
+
+## What “Ask” Does
+
+When NeoCode prompts for approval, the UI offers three outcomes:
+
+- `once` — approve just this request
+- `always` — approve future requests matching the suggested patterns (for the rest of the current NeoCode session)
+- `reject` — deny the request
+
+The set of patterns that `always` would approve is provided by the tool (for example, bash approvals typically whitelist a safe command prefix like `git status*`).
+
+---
+
+## Agents
+
+You can override permissions per agent. Agent permissions are merged with the global config, and agent rules take precedence. [Learn more](/docs/agents#permissions) about agent permissions.
+
+:::note
+Refer to the [Granular Rules (Object Syntax)](#granular-rules-object-syntax) section above for more detailed pattern matching examples.
+:::
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "permission": {
+    "bash": {
+      "*": "ask",
+      "git *": "allow",
+      "git commit *": "deny",
+      "git push *": "deny",
+      "grep *": "allow"
+    }
+  },
+  "agent": {
+    "build": {
+      "permission": {
+        "bash": {
+          "*": "ask",
+          "git *": "allow",
+          "git commit *": "ask",
+          "git push *": "deny",
+          "grep *": "allow"
+        }
+      }
+    }
+  }
+}
+```
+
+You can also configure agent permissions in Markdown:
+
+```markdown title="~/.config/neocode/agents/review.md"
+---
+description: Code review without edits
+mode: subagent
+permission:
+  edit: deny
+  bash: ask
+  webfetch: deny
+---
+
+Only analyze code and suggest changes.
+```
+
+:::tip
+Use pattern matching for commands with arguments. `"grep *"` allows `grep pattern file.txt`, while `"grep"` alone would block it. Commands like `git status` work for default behavior but require explicit permission (like `"git status *"`) when arguments are passed.
+:::

package/src/content/docs/plugins.mdx

@@ -0,0 +1,362 @@
+---
+title: Plugins
+description: Write your own plugins to extend NeoCode.
+---
+
+Plugins allow you to extend NeoCode by hooking into various events and customizing behavior. You can create plugins to add new features, integrate with external services, or modify NeoCode's default behavior.
+
+For examples, check out the [plugins](/docs/ecosystem#plugins) created by the community.
+
+---
+
+## Use a plugin
+
+There are two ways to load plugins.
+
+---
+
+### From local files
+
+Place JavaScript or TypeScript files in the plugin directory.
+
+- `.neocode/plugins/` - Project-level plugins
+- `~/.config/neocode/plugins/` - Global plugins
+
+Files in these directories are automatically loaded at startup.
+
+---
+
+### From npm
+
+Specify npm packages in your config file.
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "plugin": ["neocode-helicone-session", "neocode-wakatime", "@my-org/custom-plugin"]
+}
+```
+
+Both regular and scoped npm packages are supported.
+
+Browse available plugins in the [ecosystem](/docs/ecosystem#plugins).
+
+---
+
+### How plugins are installed
+
+**npm plugins** are installed automatically using Bun at startup. Packages and their dependencies are cached in `~/.cache/neocode/node_modules/`.
+
+**Local plugins** are loaded directly from the plugin directory. To use external packages, you must create a `package.json` within your config directory (see [Dependencies](#dependencies)), or publish the plugin to npm and [add it to your config](/docs/config#plugins).
+
+---
+
+### Load order
+
+Plugins are loaded from all sources and all hooks run in sequence. The load order is:
+
+1. Global config (`~/.config/neocode/neocode.json`)
+2. Project config (`neocode.json`)
+3. Global plugin directory (`~/.config/neocode/plugins/`)
+4. Project plugin directory (`.neocode/plugins/`)
+
+Duplicate npm packages with the same name and version are loaded once. However, a local plugin and an npm plugin with similar names are both loaded separately.
+
+---
+
+## Create a plugin
+
+A plugin is a **JavaScript/TypeScript module** that exports one or more plugin
+functions. Each function receives a context object and returns a hooks object.
+
+---
+
+### Dependencies
+
+Local plugins and custom tools can use external npm packages. Add a `package.json` to your config directory with the dependencies you need.
+
+```json title=".neocode/package.json"
+{
+  "dependencies": {
+    "shescape": "^2.1.0"
+  }
+}
+```
+
+NeoCode runs `bun install` at startup to install these. Your plugins and tools can then import them.
+
+```ts title=".neocode/plugins/my-plugin.ts"
+import { escape } from "shescape"
+
+export const MyPlugin = async (ctx) => {
+  return {
+    "tool.execute.before": async (input, output) => {
+      if (input.tool === "bash") {
+        output.args.command = escape(output.args.command)
+      }
+    },
+  }
+}
+```
+
+---
+
+### Basic structure
+
+```js title=".neocode/plugins/example.js"
+export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
+  console.log("Plugin initialized!")
+
+  return {
+    // Hook implementations go here
+  }
+}
+```
+
+The plugin function receives:
+
+- `project`: The current project information.
+- `directory`: The current working directory.
+- `worktree`: The git worktree path.
+- `client`: An neocode SDK client for interacting with the AI.
+- `$`: Bun's [shell API](https://bun.com/docs/runtime/shell) for executing commands.
+
+---
+
+### TypeScript support
+
+For TypeScript plugins, you can import types from the plugin package:
+
+```ts title="my-plugin.ts" {1}
+import type { Plugin } from "@neocode-ai/plugin"
+
+export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
+  return {
+    // Type-safe hook implementations
+  }
+}
+```
+
+---
+
+### Events
+
+Plugins can subscribe to events as seen below in the Examples section. Here is a list of the different events available.
+
+#### Command Events
+
+- `command.executed`
+
+#### File Events
+
+- `file.edited`
+- `file.watcher.updated`
+
+#### Installation Events
+
+- `installation.updated`
+
+#### LSP Events
+
+- `lsp.client.diagnostics`
+- `lsp.updated`
+
+#### Message Events
+
+- `message.part.removed`
+- `message.part.updated`
+- `message.removed`
+- `message.updated`
+
+#### Permission Events
+
+- `permission.asked`
+- `permission.replied`
+
+#### Server Events
+
+- `server.connected`
+
+#### Session Events
+
+- `session.created`
+- `session.compacted`
+- `session.deleted`
+- `session.diff`
+- `session.error`
+- `session.idle`
+- `session.status`
+- `session.updated`
+
+#### Todo Events
+
+- `todo.updated`
+
+#### Tool Events
+
+- `tool.execute.after`
+- `tool.execute.before`
+
+#### TUI Events
+
+- `tui.prompt.append`
+- `tui.command.execute`
+- `tui.toast.show`
+
+---
+
+## Examples
+
+Here are some examples of plugins you can use to extend neocode.
+
+---
+
+### Send notifications
+
+Send notifications when certain events occur:
+
+```js title=".neocode/plugins/notification.js"
+export const NotificationPlugin = async ({ project, client, $, directory, worktree }) => {
+  return {
+    event: async ({ event }) => {
+      // Send notification on session completion
+      if (event.type === "session.idle") {
+        await $`osascript -e 'display notification "Session completed!" with title "neocode"'`
+      }
+    },
+  }
+}
+```
+
+We are using `osascript` to run AppleScript on macOS. Here we are using it to send notifications.
+
+:::note
+If you’re using the NeoCode desktop app, it can send system notifications automatically when a response is ready or when a session errors.
+:::
+
+---
+
+### .env protection
+
+Prevent neocode from reading `.env` files:
+
+```javascript title=".neocode/plugins/env-protection.js"
+export const EnvProtection = async ({ project, client, $, directory, worktree }) => {
+  return {
+    "tool.execute.before": async (input, output) => {
+      if (input.tool === "read" && output.args.filePath.includes(".env")) {
+        throw new Error("Do not read .env files")
+      }
+    },
+  }
+}
+```
+
+---
+
+### Custom tools
+
+Plugins can also add custom tools to neocode:
+
+```ts title=".neocode/plugins/custom-tools.ts"
+import { type Plugin, tool } from "@neocode-ai/plugin"
+
+export const CustomToolsPlugin: Plugin = async (ctx) => {
+  return {
+    tool: {
+      mytool: tool({
+        description: "This is a custom tool",
+        args: {
+          foo: tool.schema.string(),
+        },
+        async execute(args, context) {
+          const { directory, worktree } = context
+          return `Hello ${args.foo} from ${directory} (worktree: ${worktree})`
+        },
+      }),
+    },
+  }
+}
+```
+
+The `tool` helper creates a custom tool that neocode can call. It takes a Zod schema function and returns a tool definition with:
+
+- `description`: What the tool does
+- `args`: Zod schema for the tool's arguments
+- `execute`: Function that runs when the tool is called
+
+Your custom tools will be available to neocode alongside built-in tools.
+
+---
+
+### Logging
+
+Use `client.app.log()` instead of `console.log` for structured logging:
+
+```ts title=".neocode/plugins/my-plugin.ts"
+export const MyPlugin = async ({ client }) => {
+  await client.app.log({
+    service: "my-plugin",
+    level: "info",
+    message: "Plugin initialized",
+    extra: { foo: "bar" },
+  })
+}
+```
+
+Levels: `debug`, `info`, `warn`, `error`. See [SDK documentation](https://neo.khulnasoft.com/docs/sdk) for details.
+
+---
+
+### Compaction hooks
+
+Customize the context included when a session is compacted:
+
+```ts title=".neocode/plugins/compaction.ts"
+import type { Plugin } from "@neocode-ai/plugin"
+
+export const CompactionPlugin: Plugin = async (ctx) => {
+  return {
+    "experimental.session.compacting": async (input, output) => {
+      // Inject additional context into the compaction prompt
+      output.context.push(`
+## Custom Context
+
+Include any state that should persist across compaction:
+- Current task status
+- Important decisions made
+- Files being actively worked on
+`)
+    },
+  }
+}
+```
+
+The `experimental.session.compacting` hook fires before the LLM generates a continuation summary. Use it to inject domain-specific context that the default compaction prompt would miss.
+
+You can also replace the compaction prompt entirely by setting `output.prompt`:
+
+```ts title=".neocode/plugins/custom-compaction.ts"
+import type { Plugin } from "@neocode-ai/plugin"
+
+export const CustomCompactionPlugin: Plugin = async (ctx) => {
+  return {
+    "experimental.session.compacting": async (input, output) => {
+      // Replace the entire compaction prompt
+      output.prompt = `
+You are generating a continuation prompt for a multi-agent swarm session.
+
+Summarize:
+1. The current task and its status
+2. Which files are being modified and by whom
+3. Any blockers or dependencies between agents
+4. The next steps to complete the work
+
+Format as a structured prompt that a new agent can use to resume work.
+`
+    },
+  }
+}
+```
+
+When `output.prompt` is set, it completely replaces the default compaction prompt. The `output.context` array is ignored in this case.