lcode-cli 0.8.0__tar.gz → 0.10.0__tar.gz

{lcode_cli-0.8.0 → lcode_cli-0.10.0}/CHANGELOG.md

@@ -6,6 +6,47 @@ All notable changes to lcode are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-10-05
+
+### Added
+
+- Custom commands: prompt templates in `.lcode/commands/<name>.md` or
+  `~/.config/lcode/commands/`, run as `/name args`, with `$ARGUMENTS` and `$1`…`$9`, and an
+  optional frontmatter for the description, an argument hint and the tools allowed for the
+  request.
+- Skills in the [Agent Skills](https://agentskills.io) format, from `.lcode/skills/`,
+  `.agents/skills/` and `.claude/skills/` (in the repository and in your home folder). Only their
+  names and descriptions are in the system prompt; the model loads a skill's instructions with the
+  new `skill` tool when a task matches, and its scripts and reference files when the instructions
+  call for them. `/name` starts a skill yourself. `/help` lists commands and skills and where each
+  comes from. The `skills` setting limits them to lcode's own folders (`lcode`) or turns them off.
+  An example command and skill are in `examples/`. See
+  [Commands and skills](https://nasser1941.github.io/lcode/commands/).
+
+### Changed
+
+- A repository's own commands, skills and agents are used only after you approve them; lcode asks
+  the first time and again when they change, like a project's `.mcp.json`. Custom agents from a
+  repository (new in 0.8.0) used to load without asking.
+
+## [0.9.0] - 2026-10-05
+
+### Added
+
+- Plan mode: a `plan` permission mode (Shift+Tab from `ask`, `/mode plan`, `lcode --plan`, or
+  `/plan <request>`) in which the model can read, search, run read-only commands, use the web and
+  read-only subagents, but can't change anything. It presents a plan with the new `present_plan`
+  tool, and you approve it (in `ask` or `auto-edit` mode), edit it, save it to `.lcode/plans/`, or
+  send it back with feedback. An approved plan fills the todo list and is kept through compaction;
+  `/plan` shows it. See [Plan mode](https://nasser1941.github.io/lcode/usage/#plan-mode).
+
+### Fixed
+
+- `lcode mcp add` shows the default value in its questions again, such as `AWS region
+  [us-east-1]`; the terminal formatting swallowed it.
+- The end-of-session "Worth remembering?" list shows each note's type (`[feedback]`, `[project]`, …),
+  which the same problem hid.
+
 ## [0.8.0] - 2026-10-05
 
 ### Added
@@ -246,7 +287,9 @@ First public release.
 - `AGENTS.md` project instructions and `/init` to generate them.
 - One-line installer for Linux and macOS.
 
-[Unreleased]: https://github.com/nasser1941/lcode/compare/v0.8.0...HEAD
+[Unreleased]: https://github.com/nasser1941/lcode/compare/v0.10.0...HEAD
+[0.10.0]: https://github.com/nasser1941/lcode/compare/v0.9.0...v0.10.0
+[0.9.0]: https://github.com/nasser1941/lcode/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/nasser1941/lcode/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/nasser1941/lcode/compare/v0.6.1...v0.7.0
 [0.6.1]: https://github.com/nasser1941/lcode/compare/v0.6.0...v0.6.1

{lcode_cli-0.8.0 → lcode_cli-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lcode-cli
-Version: 0.8.0
+Version: 0.10.0
 Summary: A local-first terminal coding agent powered by open-weight models on your own GPU or Mac, via Ollama.
 Project-URL: Homepage, https://nasser1941.github.io/lcode/
 Project-URL: Documentation, https://nasser1941.github.io/lcode/
@@ -80,6 +80,10 @@ through [Ollama](https://ollama.com), and when it needs current information it c
   your approval. `auto-edit` and `yolo` modes when you want speed.
 - **Sandbox (optional).** `lcode --sandbox` runs the model's shell commands in a container (Docker or
   Podman) that only sees your project, without network access unless you allow it.
+- **Commands and skills.** Your own `/commands` as prompt templates, and skills in the
+  [Agent Skills](https://agentskills.io) format that the model loads only when a task needs them.
+- **Plan mode.** `/plan <request>` or Shift+Tab: the model explores read-only and presents a plan;
+  you approve, edit or send it back before anything changes.
 - **Undo.** lcode saves a checkpoint before the model changes files; `/undo` takes back the last
   request's edits, new files and shell-command changes, without touching your git history.
 - **Subagents.** The model hands broad searches, planning and self-contained changes to subagents
@@ -195,7 +199,6 @@ fills up. Details: [How it works](https://nasser1941.github.io/lcode/how-it-work
 
 See the pinned [Roadmap issue](https://github.com/nasser1941/lcode/issues/10). Next up:
 
-- [Plan mode](https://github.com/nasser1941/lcode/issues/41) and [custom commands and skills](https://github.com/nasser1941/lcode/issues/42)
 - [Ready-made MCP for Metabase, Encord and Valohai](https://github.com/nasser1941/lcode/issues/53)
 - Then: [smarter context for small windows](https://github.com/nasser1941/lcode/issues/46), [language servers](https://github.com/nasser1941/lcode/issues/44), [a repository map with local embeddings](https://github.com/nasser1941/lcode/issues/45), [hooks](https://github.com/nasser1941/lcode/issues/43)
 - More models in the catalog, and test reports from your hardware ([report one](https://github.com/nasser1941/lcode/issues/new?template=model_request.yml))

{lcode_cli-0.8.0 → lcode_cli-0.10.0}/README.md

@@ -46,6 +46,10 @@ through [Ollama](https://ollama.com), and when it needs current information it c
   your approval. `auto-edit` and `yolo` modes when you want speed.
 - **Sandbox (optional).** `lcode --sandbox` runs the model's shell commands in a container (Docker or
   Podman) that only sees your project, without network access unless you allow it.
+- **Commands and skills.** Your own `/commands` as prompt templates, and skills in the
+  [Agent Skills](https://agentskills.io) format that the model loads only when a task needs them.
+- **Plan mode.** `/plan <request>` or Shift+Tab: the model explores read-only and presents a plan;
+  you approve, edit or send it back before anything changes.
 - **Undo.** lcode saves a checkpoint before the model changes files; `/undo` takes back the last
   request's edits, new files and shell-command changes, without touching your git history.
 - **Subagents.** The model hands broad searches, planning and self-contained changes to subagents
@@ -161,7 +165,6 @@ fills up. Details: [How it works](https://nasser1941.github.io/lcode/how-it-work
 
 See the pinned [Roadmap issue](https://github.com/nasser1941/lcode/issues/10). Next up:
 
-- [Plan mode](https://github.com/nasser1941/lcode/issues/41) and [custom commands and skills](https://github.com/nasser1941/lcode/issues/42)
 - [Ready-made MCP for Metabase, Encord and Valohai](https://github.com/nasser1941/lcode/issues/53)
 - Then: [smarter context for small windows](https://github.com/nasser1941/lcode/issues/46), [language servers](https://github.com/nasser1941/lcode/issues/44), [a repository map with local embeddings](https://github.com/nasser1941/lcode/issues/45), [hooks](https://github.com/nasser1941/lcode/issues/43)
 - More models in the catalog, and test reports from your hardware ([report one](https://github.com/nasser1941/lcode/issues/new?template=model_request.yml))

{lcode_cli-0.8.0 → lcode_cli-0.10.0}/docs/agents.md

@@ -134,7 +134,9 @@ Report bugs first, with `path:line`, then missing tests, then style. Don't fix a
 | `~/.config/lcode/agents/<name>.md` | For every repository |
 
 The file name is the agent's name. A repository's agent overrides one of yours with the same name,
-and both override the built-in types. `/agents` and `lcode doctor` point out files that couldn't be
+and both override the built-in types. A repository's agents are used only after you
+[approve them](commands.md#approving-a-repositorys-commands-skills-and-agents), together with its
+commands and skills. `/agents` and `lcode doctor` point out files that couldn't be
 read.
 
 ## Settings

lcode_cli-0.10.0/docs/commands.md

@@ -0,0 +1,131 @@
+# Commands and skills
+
+Teams repeat the same requests: "review this diff against our checklist", "write a migration the
+way we do it", the release steps. `AGENTS.md` can't hold all of that, because it goes into every
+request and every line costs context. lcode has two ways to keep such instructions ready without
+paying for them until they're used.
+
+| | Command | Skill |
+|---|---|---|
+| What it is | A prompt template | Instructions, plus scripts and reference files if needed |
+| Who starts it | You, with `/name args` | The model, when a task matches its description, or you with `/name` |
+| Context cost until used | Nothing | Its name and one-line description |
+| Format | `<name>.md` | A folder with a `SKILL.md`, in the [Agent Skills](https://agentskills.io) format |
+
+## Commands
+
+A command is a markdown file whose body is the request to send. `$ARGUMENTS` becomes everything
+you type after the command's name, and `$1` to `$9` single words. If the template has no
+placeholder, what you type is added at the end.
+
+```markdown
+---
+description: review the uncommitted changes for bugs and missing tests
+argument-hint: "[path or what to focus on]"
+allowed-tools: read_file grep glob list_dir bash
+---
+Review the uncommitted changes in this repository. $ARGUMENTS
+
+Run `git diff` and `git diff --cached` to see them, and read the code around them where needed.
+Report bugs first, with `path:line`, then missing tests. Don't change any files.
+```
+
+```text
+❯ /review the parser changes
+```
+
+| Frontmatter (all optional) | |
+|---|---|
+| `description` | Shown in `/help` and completion (default: the first line) |
+| `argument-hint` | Shown after the name in `/help`, e.g. `[path]` |
+| `allowed-tools` | The only tools the model gets for this request, e.g. `read_file grep bash` (lcode's tool names) |
+
+| Folder | Commands |
+|---|---|
+| `.lcode/commands/<name>.md` in the repository | For this repository; commit them to share them |
+| `~/.config/lcode/commands/<name>.md` | For every repository |
+
+The file name is the command's name. A repository's command overrides one of yours with the same
+name; built-in commands such as `/help` can't be replaced.
+
+## Skills
+
+A skill is a folder with a `SKILL.md`: a frontmatter with a `name` and a `description` that says
+what the skill does and when to use it, then instructions. Scripts, templates and reference files
+can sit next to it.
+
+```text
+.lcode/skills/commit-message/
+├── SKILL.md
+└── scripts/
+    └── staged.sh
+```
+
+```markdown
+---
+name: commit-message
+description: Writes a git commit message for the staged changes, in the style the repository
+  already uses. Use when the user asks for a commit message, or asks you to commit their changes.
+---
+# Commit messages
+
+1. Run `scripts/staged.sh` from this skill's folder. It prints the staged files and the subjects
+   of the last 15 commits.
+2. Match the style of the recent subjects …
+```
+
+How lcode uses them, step by step, so they cost almost nothing until needed:
+
+1. At the start of a session, the model gets only each skill's name and description.
+2. When a task matches a description, the model calls the `skill` tool. It gets the instructions,
+   the skill's folder and the list of files in it, but not their contents.
+3. The model reads or runs those files when the instructions call for them. Files in a skill's
+   folder can be read even when the [sandbox](sandbox.md) limits the model to the project.
+
+You can also start a skill yourself: `/commit-message` or `/commit-message only the parser
+changes`. After the conversation is compacted, the model is told which skills were in use, so it
+can load them again.
+
+lcode reads skills from these folders; a repository's skill overrides one of yours with the same
+name:
+
+| Folder | |
+|---|---|
+| `.lcode/skills/`, `.agents/skills/`, `.claude/skills/` in the repository | For this repository |
+| `~/.config/lcode/skills/`, `~/.agents/skills/`, `~/.claude/skills/` | For every repository |
+
+`.agents/skills/` is the folder agents share by convention, and `.claude/skills/` is read too, so
+skills you already have for other agents work in lcode. If other agents installed many skills you
+don't need here, `lcode config set skills lcode` limits lcode to its own folders (`skills off` turns
+skills off). However many there are, the list in the model's instructions stays within about 5% of
+the context window: with many skills, each description is shortened so that all of them stay
+listed. The same skill installed in two folders is used once. The format is the
+[Agent Skills specification](https://agentskills.io/specification); like other agents, lcode is
+lenient with skills that bend its rules (a name with capital letters, an unquoted colon in a
+description) and skips only those without a description. `/help` lists the skills it found and
+any it skipped.
+
+## Approving a repository's commands, skills and agents
+
+A repository's commands, skills and [agents](agents.md#custom-agents) steer the model, and skills
+can bring scripts. A freshly cloned repository shouldn't be able to do that silently, so the first
+time you start lcode in a repository that has any, it asks:
+
+```text
+This repository brings its own commands, skills or agents:
+  commands: /review
+  skills: commit-message
+They can steer the model and include scripts it may run (commands still ask first, unless you
+allow them).
+  Use them? [y/N]
+```
+
+lcode asks again whenever any of their files change. Until you say yes, only your own commands and
+skills are used. `lcode -p` never asks and doesn't use them.
+
+## Examples
+
+The lcode repository has a ready-made command and skill in
+[`examples/`](https://github.com/nasser1941/lcode/tree/main/examples): `/review` and the
+`commit-message` skill above. Copy them into `.lcode/` of a repository, or into
+`~/.config/lcode/` to have them everywhere.

{lcode_cli-0.8.0 → lcode_cli-0.10.0}/docs/configuration.md

@@ -20,7 +20,7 @@ lcode config path                      # print the file location
 | `num_batch` | 512 | Prompt batch size. Larger reads prompts faster but needs more GPU memory |
 | `keep_alive` | `30m` | How long Ollama keeps the model in memory after the last request |
 | `ollama_host` | `http://localhost:11434` | Ollama server URL |
-| `permission_mode` | `ask` | `ask`, `auto-edit` or `yolo` |
+| `permission_mode` | `ask` | `ask`, `plan`, `auto-edit` or `yolo` |
 | `think` | `true` | Let the model reason before answering |
 | `web` | `on` | Web search and page fetching: `on`, `ask` (before each search/website) or `off` |
 | `search_backend` | `auto` | `auto`, `ollama`, `brave`, `tavily` or `searxng`; `auto` uses the first one configured |
@@ -31,6 +31,7 @@ lcode config path                      # print the file location
 | `vision_model` | `auto` | The model that [looks at images](usage.md#images): `auto`, `off` or an Ollama model that can see |
 | `mcp_tools` | `auto` | How [MCP](mcp.md#context) tool definitions reach the model: `auto`, `direct` or `search` (on demand) |
 | `memory` | `ask` | [Notes that carry over](memory.md) to later sessions: `ask` (confirm each), `auto` or `off` |
+| `skills` | `all` | Which [skills](commands.md#skills) the model is offered: `all` (lcode's folders and the ones other agents share), `lcode` (only `.lcode/skills/` and `~/.config/lcode/skills/`) or `off` |
 | `subagents` | `true` | Let the model hand tasks to [subagents](agents.md) with their own context |
 | `max_parallel_agents` | `1` | Subagents that run at the same time; more needs `OLLAMA_NUM_PARALLEL` on the Ollama server ([details](agents.md#several-at-once)) |
 | `checkpoints` | `true` | Save a checkpoint before the model changes files, so [`/undo`](usage.md#undo-and-checkpoints) can restore them |
@@ -74,6 +75,8 @@ Environment variables override the file, which is useful for one-off runs and CI
 | `~/.local/state/lcode/mcp-logs/` | Error output of local MCP servers |
 | `~/.local/state/lcode/checkpoints/` | Checkpoints for `/undo` (copies of your project's files; deleted after 14 days) |
 | `~/.local/state/lcode/memory/` | [Memory](memory.md) notes: `user/` for every repository, `projects/<repository>/` for each one |
+| `~/.config/lcode/commands/`, `~/.config/lcode/skills/` | Your [commands and skills](commands.md) (a repository's go in `.lcode/`) |
+| `~/.local/state/lcode/extensions-approved.json` | Repositories whose commands, skills and agents you approved |
 | `~/.config/lcode/agents/` | Your [custom agents](agents.md#custom-agents) (a repository's go in `.lcode/agents/`) |
 | `~/.local/state/lcode/limits.json` | Context sizes that ran out of GPU memory on this machine (safe to delete) |
 

{lcode_cli-0.8.0 → lcode_cli-0.10.0}/docs/how-it-works.md

@@ -89,6 +89,9 @@ the Ollama server you configure, it only contacts the web when the model searche
 | `bench.py` | `lcode bench`: the benchmark tasks, their checks and the reports |
 | `vision.py` | Looking at images with a model that can see |
 | `subagents.py` | Subagents: agent types, running them (also in parallel), worktrees for workers |
+| `extensions.py` | Custom commands and skills, and approving a repository's own |
+| `frontmatter.py` | The `---` headers of notes, agents, commands and skills |
+| `planning.py` | Plan mode: what it allows, presenting a plan and approving it |
 | `memory.py` | Notes that carry over between sessions, and the end-of-session check |
 | `sandbox.py` | The optional container for shell commands |
 | `checkpoints.py` | Snapshots before the model changes files, for `/undo` and `/rewind` |

{lcode_cli-0.8.0 → lcode_cli-0.10.0}/docs/quickstart.md

@@ -12,7 +12,7 @@ lcode
 
 ```text
 ╭──────────────────────────────────────────────╮
-│ lcode v0.8.0 — local coding agent            │
+│ lcode v0.10.0 — local coding agent           │
 │                                              │
 │ model    lcode-qwen3.6-35b                   │
 │ context  256K tokens                         │

{lcode_cli-0.8.0 → lcode_cli-0.10.0}/docs/usage.md

@@ -20,6 +20,7 @@ lcode mcp [catalog|add|list] # connect MCP servers: Jira, GitHub, AWS, databases
 | `-r, --repo DIR` | Work in another directory |
 | `-c, --continue` | Continue the most recently used session in this directory |
 | `--resume [SESSION]` | Resume a saved session: pick from a list, or give its number, name or id |
+| `--plan` | Start in [plan mode](#plan-mode): agree on a plan before anything changes |
 | `--auto-edit` | Apply file edits without asking (commands still ask) |
 | `--yolo` | Never ask for permission |
 | `--no-think` | Turn off the model's reasoning: faster, less accurate |
@@ -38,7 +39,7 @@ lcode mcp [catalog|add|list] # connect MCP servers: Jira, GitHub, AWS, databases
 | ++esc++ ++enter++ or a trailing `\` | New line |
 | ++ctrl+c++ | Interrupt the model or a running command |
 | ++ctrl+d++ | Quit |
-| ++shift+tab++ | Cycle permission mode: ask → auto-edit → yolo |
+| ++shift+tab++ | Cycle permission mode: ask → plan → auto-edit → yolo |
 | ++tab++ | Complete slash commands and `@` paths |
 | `@path` | Attach a file (or a directory listing) to your message |
 | `@name` | Ask for a [subagent](agents.md) of that type, e.g. `@plan` |
@@ -58,17 +59,19 @@ reasoning is on.
 | `/undo` | Undo the file changes of the last request ([details](#undo-and-checkpoints)) |
 | `/rewind [N]` | Go back to before request N: its files, and optionally the conversation |
 | `/checkpoints` | List the requests that changed files, and which files |
+| `/name [args]` | Run one of your [commands or skills](commands.md); `/help` lists them |
 | `/agents [N]` | [Subagent](agents.md) types, and what this session's subagents did |
 | `/remember [-g] TEXT` | Save a [note](memory.md) for later sessions (`-g`: for every repository) |
 | `/memory [show\|edit\|delete N]` | The [notes](memory.md) lcode remembers |
 | `/sandbox [network on\|off]` | The [sandbox](sandbox.md) for shell commands |
 | `/mcp [tools\|login\|restart NAME]` | [MCP servers](mcp.md), their status and tools |
+| `/plan [request]` | Work out a [plan](#plan-mode) before changing anything, or show the approved plan |
 | `/compact [focus]` | Summarize the conversation to free context |
 | `/context [size]` | Show how full the context window is and change its size: pick from a list with memory estimates, or give a size like `/context 128k` (`/ctx` is a shortcut) |
 | `/model [name]`, `/models` | Switch model, list models |
 | `/think [on\|off]` | Toggle reasoning |
 | `/verbose` | Toggle showing the reasoning text |
-| `/mode [ask\|auto-edit\|yolo]` | Set the permission mode |
+| `/mode [ask\|plan\|auto-edit\|yolo]` | Set the permission mode |
 | `/cd DIR` | Change the working directory |
 | `/todos` | Show the model's task list |
 | `/exit` | Quit |
@@ -90,6 +93,8 @@ reasoning is on.
 | `view_image` | Look at an image: a model that can see describes it ([Images](#images)) |
 | `agent` | Hand a task to a [subagent](agents.md) with its own context; only its report comes back |
 | `memory` | Save, update or delete [notes](memory.md) that later sessions load |
+| `skill` | Load a [skill](commands.md#skills)'s instructions when a task matches it |
+| `present_plan` | In [plan mode](#plan-mode): show the plan and ask for approval |
 
 lcode refuses to edit a file the model hasn't read in the session, or one that changed on disk since
 it was read, so the model always edits the current version.
@@ -127,12 +132,16 @@ image support off with `lcode config set vision_model off`.
 | Mode | File edits | Shell commands |
 |---|---|---|
 | `ask` (default) | ask | ask, except read-only commands |
+| `plan` | refused | only read-only commands ([Plan mode](#plan-mode)) |
 | `auto-edit` | automatic | ask, except read-only commands |
 | `yolo` | automatic | automatic |
 
+++shift+tab++ cycles through them in this order, `/mode` sets one, and `--plan`, `--auto-edit` and
+`--yolo` start in one.
+
 Read-only commands run without asking: `ls`, `cat`, `head`, `tail`, `grep`, `rg`, `find`, `tree`,
 `wc`, `diff`, `git status/log/diff/show/branch/blame` and similar, as long as they don't redirect
-output, chain commands or run subshells.
+output, chain commands or run subshells. A `cd <folder> &&` in front is fine.
 
 When asked, answer ++y++ (once), ++a++ (always, for this command or for all edits, until you quit)
 or ++n++. Text after ++n++ goes to the model as instructions: `n run the tests with -x first`.
@@ -146,6 +155,42 @@ or ++n++. Text after ++n++ goes to the model as instructions: `n run the tests w
 With the [sandbox](sandbox.md) on, `auto-edit` mode runs shell commands without asking too: they can
 only reach the project, and `/undo` can take their changes back.
 
+## Plan mode
+
+Local models are slower than cloud models and make more mistakes, so on a bigger change it pays to
+agree on the approach before the model starts editing. In **plan mode** the model can read, search,
+run read-only commands, use the web and [explore and plan subagents](agents.md), but it can't
+change anything. It ends by presenting a plan: numbered steps, the files it will change, the risks
+and how it will verify the work.
+
+```text
+❯ /plan add retries to the webhook handlers
+  …
+╭─ Plan: Retries for webhook handlers ───────────────────────────────────────────╮
+│ 1. Wrap the HTTP call in payments/webhooks.py:88 in a retry loop (3 tries, …)  │
+│ 2. Add tests for a timeout and a 500 in tests/test_webhooks.py                 │
+│ Risks: duplicate deliveries if the endpoint isn't idempotent …                 │
+│ Verify: pytest tests/test_webhooks.py                                          │
+╰────────────────────────────────────────────────────────────────────────────────╯
+  [y] run it, asking before changes · [a] run it, edits without asking (auto-edit)
+  [e] edit the plan · [s] save it to .lcode/plans/ · [n] keep planning (+ what to change)
+  >
+```
+
+| Answer | |
+|---|---|
+| ++y++ or ++enter++ | Approve: lcode switches to `ask` mode and the model starts on the plan right away |
+| ++a++ | Approve and switch to `auto-edit`, so file edits don't ask |
+| ++e++ | Edit the plan in your editor first; the model follows your version |
+| ++s++ | Save it as `.lcode/plans/<title>.md`, for example to share it or commit it |
+| ++n++ + text | Send it back: `n keep the old API working` |
+
+After approval, the todo list is filled from the plan's numbered steps, and the plan is kept word
+for word when the conversation is compacted. `/plan` shows the approved plan.
+
+Start planning with `/plan <request>` (switches to plan mode and sends the request), with
+++shift+tab++ (one step from `ask`), or with `lcode --plan`.
+
 ## Undo and checkpoints
 
 Before the model first changes anything in a request (an edit, a new file, or a shell command that
@@ -233,6 +278,9 @@ At startup lcode reads `AGENTS.md` (or `LCODE.md`, or `CLAUDE.md`) from the work
 adds it to the model's instructions. Use it for build and test commands, architecture notes and
 conventions. `/init` writes a first version for you.
 
+Instructions that are only needed for some tasks fit better in a [command or skill](commands.md),
+which costs no context until it's used.
+
 What doesn't belong in `AGENTS.md` but should carry over, such as your corrections and preferences,
 goes into lcode's [memory](memory.md): short notes the model, you (`/remember`) or a short check at
 the end of a session save, and that every later session in the repository loads.

lcode_cli-0.10.0/examples/README.md

@@ -0,0 +1,17 @@
+# Examples
+
+Ready-made extensions for lcode. Copy them into a repository (or into `~/.config/lcode/` to use
+them everywhere):
+
+| Example | Copy to | Use it |
+|---|---|---|
+| [`commands/review.md`](commands/review.md) | `.lcode/commands/review.md` | `/review` or `/review the parser` |
+| [`skills/commit-message/`](skills/commit-message/) | `.lcode/skills/commit-message/` | ask for a commit message, or `/commit-message` |
+
+```bash
+mkdir -p .lcode/commands .lcode/skills
+cp examples/commands/review.md .lcode/commands/
+cp -r examples/skills/commit-message .lcode/skills/
+```
+
+See [Commands and skills](https://nasser1941.github.io/lcode/commands/) for the format.

lcode_cli-0.10.0/examples/commands/review.md

@@ -0,0 +1,15 @@
+---
+description: review the uncommitted changes for bugs and missing tests
+argument-hint: "[path or what to focus on]"
+allowed-tools: read_file grep glob list_dir bash
+---
+Review the uncommitted changes in this repository. $ARGUMENTS
+
+Run `git diff` and `git diff --cached` to see them, and read the code around them where needed.
+
+Report, most important first:
+1. Bugs: wrong behavior, unhandled errors and edge cases, with `path:line`.
+2. Missing or weak tests for the changed behavior.
+3. Anything that doesn't match the code around it.
+
+Don't change any files.

lcode_cli-0.10.0/examples/skills/commit-message/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: commit-message
+description: Writes a git commit message for the staged changes, in the style the repository already uses. Use when the user asks for a commit message, or asks you to commit their changes.
+license: MIT
+---
+# Commit messages
+
+1. Run `scripts/staged.sh` from this skill's folder (with its absolute path). It prints the staged
+   files and the subjects of the last 15 commits.
+2. If nothing is staged, tell the user and stop. Don't stage files yourself unless they asked.
+3. Read the staged diff (`git diff --cached`) of the files that matter.
+4. Match the style of the recent subjects: imperative mood or not, prefixes such as `feat:` or
+   `fix(scope):` only if the repository uses them, capitalization and length.
+5. Write a subject under 72 characters that says what the change does. For anything but a trivial
+   change, add a blank line and a short body that says why, wrapped at 72 characters.
+6. Show the message. Commit only if the user asked you to: `git commit -F -` with the message on
+   standard input.

lcode_cli-0.10.0/examples/skills/commit-message/scripts/staged.sh

@@ -0,0 +1,8 @@
+#!/bin/sh
+# The staged changes and recent commit subjects, for a commit message in the repository's style.
+set -e
+echo "Staged files:"
+git diff --cached --stat
+echo
+echo "Recent commit subjects:"
+git log --format='%s' -15

{lcode_cli-0.8.0 → lcode_cli-0.10.0}/mkdocs.yml

@@ -94,6 +94,7 @@ nav:
       - Using lcode: usage.md
       - Memory: memory.md
       - Subagents: agents.md
+      - Commands and skills: commands.md
       - Models & context windows: models.md
       - Benchmarking models: bench.md
       - MCP servers: mcp.md

{lcode_cli-0.8.0 → lcode_cli-0.10.0}/pyproject.toml

@@ -71,6 +71,8 @@ ignore = [
 "src/lcode/agent.py" = ["E501"] # the prompts are prose; wrapping them would change what the model sees
 "src/lcode/memory.py" = ["E501"]
 "src/lcode/subagents.py" = ["E501"]
+"src/lcode/planning.py" = ["E501"]
+"src/lcode/extensions.py" = ["E501"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{lcode_cli-0.8.0 → lcode_cli-0.10.0}/src/lcode/__init__.py

@@ -1,3 +1,3 @@
 """lcode — a local-first terminal coding agent powered by open-weight models via Ollama."""
 
-__version__ = "0.8.0"
+__version__ = "0.10.0"

{lcode_cli-0.8.0 → lcode_cli-0.10.0}/src/lcode/agent.py

@@ -21,7 +21,7 @@ from rich.markup import escape
 from rich.panel import Panel
 from rich.text import Text
 
-from lcode import catalog, limits, sessions, subagents, vision, web
+from lcode import catalog, extensions, limits, planning, sessions, subagents, vision, web
 from lcode import memory as memory_notes
 from lcode.checkpoints import Checkpoints
 from lcode.config import format_tokens
@@ -32,6 +32,7 @@ from lcode.render import MarkdownStreamer
 from lcode.sandbox import Sandbox, SandboxError, project_root
 from lcode.tools import (
     MEMORY_SCHEMA,
+    PRESENT_PLAN_SCHEMA,
     SCHEMAS,
     VIEW_IMAGE_SCHEMA,
     WEB_FETCH_SCHEMA,
@@ -77,7 +78,7 @@ SYSTEM_PROMPT = """You are lcode, an autonomous software-engineering agent runni
 
 # Top-level layout of the working directory
 {tree}
-{web}{agents}{project}{notes}"""
+{web}{agents}{skills}{project}{notes}"""
 
 WEB_PROMPT = """
 # Web access
@@ -170,6 +171,8 @@ class Settings:
     vision_model: str = "auto"  # auto, off or an Ollama model that can see images
     memory: str = "off"  # off, ask or auto: notes that carry over to later sessions (lcode.memory)
     subagents: bool = False  # the agent tool (lcode.subagents)
+    trust_project: bool = False  # use the repository's own commands, skills and agents (lcode.extensions)
+    skills: str = "off"  # all, lcode (only lcode's own skill folders) or off
     max_parallel_agents: int = 1
 
 
@@ -198,6 +201,9 @@ class Agent:
         self._memory: memory_notes.Memory | None = None
         self._agent_types: tuple[Path, dict[str, subagents.AgentType], list[str]] | None = None
         self.agent_runs: list[subagents.Record] = []  # subagents run in this session, for /agents
+        self.plan = ""  # the plan the user approved; kept through compaction
+        self._extensions: tuple[Path, extensions.Extensions] | None = None
+        self.skills_loaded: set[str] = set()  # skills whose instructions are in the conversation
         # Set on subagents (see lcode.subagents):
         self.allowed_tools: set[str] | None = None  # None: every tool
         self.read_only = False  # only read-only shell commands
@@ -234,8 +240,15 @@ class Agent:
             notes=self.memory().prompt(self.settings.context) if self.settings.memory != "off" else "",
             web=self.web_prompt(),
             agents=self.agents_prompt(),
+            skills=extensions.skills_prompt(self.extensions().skills, self.settings.context),
         )
 
+    def extensions(self) -> extensions.Extensions:
+        """Custom commands and skills for the current folder (a repository's only once approved)."""
+        if self._extensions is None or self._extensions[0] != self.cwd:
+            self._extensions = (self.cwd, extensions.load(self.cwd, self.settings.trust_project, self.settings.skills))
+        return self._extensions[1]
+
     def agents_prompt(self) -> str:
         if not self.settings.subagents:
             return ""
@@ -250,7 +263,7 @@ class Agent:
     def agent_types(self) -> dict[str, subagents.AgentType]:
         """Built-in and custom agent types for the current folder."""
         if self._agent_types is None or self._agent_types[0] != self.cwd:
-            types, problems = subagents.load_types(self.cwd)
+            types, problems = subagents.load_types(self.cwd, self.settings.trust_project)
             self._agent_types = (self.cwd, types, problems)
         return self._agent_types[1]
 
@@ -259,6 +272,9 @@ class Agent:
         assert self._agent_types is not None
         return self._agent_types[2]
 
+    def planning(self) -> bool:
+        return self.perms.mode == "plan"
+
     def tool_names(self) -> set[str]:
         return {s["function"]["name"] for s in self.tool_schemas()}
 
@@ -283,6 +299,10 @@ class Agent:
             schemas.append(MEMORY_SCHEMA)
         if self.settings.subagents:
             schemas.append(subagents.schema(self.agent_types(), self.settings.max_parallel_agents))
+        if self.planning():
+            schemas.append(PRESENT_PLAN_SCHEMA)
+        if self.extensions().skills:
+            schemas.append(extensions.schema(self.extensions().skills))
         if self.mcp:
             schemas += self.mcp.schemas(self.settings.context)
         if self.allowed_tools is not None:
@@ -402,6 +422,7 @@ class Agent:
 
     def new_session(self) -> None:
         self.reset()
+        self.skills_loaded.clear()
         self.session_id = self.new_session_id()
         self.session_name = ""
         self.session_title = ""
@@ -599,6 +620,8 @@ class Agent:
             return f"list_dir({args.get('path', '.')})"
         if name == "memory":
             return f"memory({' '.join(str(args.get(k) or '') for k in ('action', 'name')).strip()})"
+        if name == "skill":
+            return f"skill({args.get('name', '')})"
         if name == "agent":
             return f"agent({args.get('type', '')}: {args.get('description') or str(args.get('task', ''))[:50]})"
         if name == "bash":
@@ -638,7 +661,8 @@ class Agent:
 
     def _run_turn(self, user_text: str, max_steps: int = MAX_STEPS_PER_TURN) -> None:
         self.prepare_mcp()
-        self.messages.append({"role": "user", "content": self.expand_mentions(user_text)})
+        note = planning.NOTE if self.planning() and self.allowed_tools is None else ""
+        self.messages.append({"role": "user", "content": self.expand_mentions(user_text) + note})
         malformed = 0
         for _ in range(max_steps):
             if self.cancel is not None and self.cancel.is_set():
@@ -777,6 +801,14 @@ class Agent:
             {"role": "user", "content": f"[Summary of our conversation so far]\n\n{summary}"},
             {"role": "assistant", "content": "Got it — I have the context from the summary and will continue."},
         ]
+        if self.plan:  # the approved plan stays word for word
+            self.messages[1]["content"] += f"\n\n[The plan the user approved; keep following it]\n\n{self.plan}"
+        if self.skills_loaded:  # their instructions were in the old messages: load them again when needed
+            names = ", ".join(sorted(self.skills_loaded))
+            self.messages[1]["content"] += (
+                f"\n\n[Skills in use before the summary: {names}. Load them again with the skill tool if you still need them.]"
+            )
+            self.skills_loaded.clear()
         self.ctx_used = sum(len(m["content"]) for m in self.messages) // 3
         self.reflected = len(self.messages)
         self.console.print(Panel(Markdown(summary), title="Compacted summary", border_style="blue"))