Plugins
Extend CodeWork with new tools and system prompt sections, installed from npm, git, or a file in your repo.
Plugins are how CodeWork learns new things. A plugin can give the agent a new tool, change how an existing tool behaves, or add instructions to the system prompt. Everything CodeWork does out of the box, from running shell commands to reading your AGENTS.md, is itself a plugin.
Terminal showing codework plugin add installing a plugin, then codework plugin list with its ID resolved.
How Plugins Work
A plugin is a JavaScript module that default-exports one plugin definition. You name it in a settings file, install it with the CLI, and CodeWork loads it at the start of every session.
- Declare it. Add an entry to the
pluginsarray in.codework/settings.jsonc(for a project) or~/.codework/settings.jsonc(for you). - Install it.
codework plugin addinstalls and declares in one step. On a fresh checkout,codework plugin installfetches everything the settings already name. - Run. Each session loads the installed plugins, runs their
setup, and hands the resulting tools and prompt to the model.
Loading never touches the network. If a plugin is declared but not installed, CodeWork tells you to run codework plugin install instead of quietly fetching it. See resolve-only loading.
Only install plugins you trust
A plugin’s code runs inside the CodeWork process with your user’s access, and CodeWork has no permission prompts: tools a plugin registers run without asking. CodeWork never runs install scripts, but the plugin itself is trusted once it loads.
Plugin Kinds
Every plugin declares a kind, which is the part of the agent it extends. The kind also decides when it runs: all tool plugins are set up before any prompt plugin, so a prompt plugin always sees the complete tool set.
| Kind | What it does | Example |
|---|---|---|
tool | Registers tools the model can call, patches another tool’s description, or guards calls with before and after hooks. | A list_processes tool that runs ps inside the sandbox. |
prompt | Writes into the system prompt: the foundation, the shared rules list, or a section of its own. | A house-style plugin that appends your team’s coding rules. |
Within one kind, plugins run in the order their entries are written, which is what lets one plugin build on another.
Built-In Plugins
CodeWork ships these plugins and turns most of them on by default. You can switch any of them on or off from settings by ID.
| ID | Kind | Default | What it adds |
|---|---|---|---|
codework.tool.bash | tool | On | Run shell commands in the session’s sandbox. |
codework.tool.read | tool | On | Read files. |
codework.tool.write | tool | On | Create or overwrite files. |
codework.tool.edit | tool | On | Make targeted edits to existing files. |
codework.tool.grep | tool | Off | Search file contents. |
codework.tool.find | tool | Off | Find files by name. |
codework.tool.ls | tool | Off | List a directory. |
codework.prompt.default | prompt | On | The base system prompt, tool guidelines, and standing rules. |
codework.prompt.instruction | prompt | On | Project instructions from AGENTS.md or CLAUDE.md files in your workspace. |
Turn on the search tools with one entry each:
{
"plugins": [
{ "plugin": "codework.tool.grep", "enabled": true },
{ "plugin": "codework.tool.find", "enabled": true },
],
}The codework. namespace is reserved for built-ins. Third-party plugins use their own vendor prefix, like acme.tool.proc.
Where Plugins Come From
| Source | Example entry | Notes |
|---|---|---|
| npm registry | @acme/codework-tool-proc@1.2.0 | Exact versions, ranges, and tags all work. |
| git repository | github:acme/codework-tool-proc#v1.2.0 | Branches, tags, and commits. Subdirectories with ::path:. |
| local file | ./plugins/house-style.ts | Loaded in place. TypeScript works with no build step. |
Installed packages live in a shared store under ~/.codework/cache, so ten projects using the same plugin share one copy. Nothing is ever written into your project except the settings entry.
FAQ
Do Plugins Need a Build Step?
Not for a local file. A plugin loaded by path can be plain TypeScript, because Node strips types outside node_modules. A plugin installed from npm or git must ship compiled JavaScript.
Does CodeWork Update Plugins Automatically?
No. A session only loads what is already installed. Run codework plugin check to see what is newer and codework plugin update to fetch it.
Can I Turn Off a Built-In Tool?
Yes. Add { "plugin": "codework.tool.bash", "enabled": false } (or any other built-in ID) to the plugins array.
Where Do Installed Plugins Live?
In a shared store under ~/.codework/cache/plugins. Nothing is written into your project except the settings entry.
Can a Project and My User Settings Both Declare Plugins?
Yes. The two lists are combined, user first, so project plugins add to your personal ones instead of replacing them.