Settings tools
Concise ships three ways for an agent or a person to read and change its settings: a CLI, an MCP server with the same operations, and two skills that drive them. Each edit is validated against the config schema and previewed as a diff. A write needs --apply (CLI) or apply: true (MCP).
CLI
node plugins/concise/scripts/concise-config.mjs <command> [arguments] [options]In an installed plugin, the script is ${CLAUDE_PLUGIN_ROOT}/scripts/concise-config.mjs. It needs Node.js only.
| Command | Result |
|---|---|
show | The effective settings and every config layer file, with BEC_ overrides and load problems. |
keys [query] | The documented keys, defaults, and descriptions from configuration.md. |
get <key> | One key: its default, the effective value, and the value in each layer file. |
set <key> <value> | Sets a key. The value is JSON, or a plain string when it does not parse. |
unset <key> | Removes a key and any parent object left empty. |
add <key> <value> | Adds items to a list key. Items already in the list are skipped. |
remove <key> <value> | Removes items from a list key. |
validate | Validates every layer file and reports load problems. |
check [text] | Runs the checks over text from the argument, --file, or stdin. Retry and confirmation state stay unchanged. |
dict list | Dictionary entries and the layer that sets each one. |
dict add | Adds an entry from --value, --fix, --match, --on, --id, --hooks, --scopes, --flags, and --case-sensitive. |
dict remove <id> | Removes an entry from a layer. --disable switches off an entry that another layer sets. |
dict test [text] | Runs an entry built from the flags over text without saving it. |
tune <path>... | Proposes settings that fit writing samples. See Tuner. |
| Option | Meaning |
|---|---|
--cwd <dir> | Project directory. Default: the current directory. |
--layer <name> | project (default), user, or a layer id from show. |
--apply | Writes the change. Without it, edit commands print the diff only. |
--json | Prints the raw result. |
--scope, --hook, --path | The text scope, the hook to imitate, and the file path for check and dict test. |
--kind, --preset | The sample kind and the base preset for tune. |
--layer project writes the project file in effect. When no project file exists, it writes .claude/concise.json, or .codex/concise.json when only .codex/ exists. --layer user writes the user file in effect, else $XDG_CONFIG_HOME/concise/concise.json or ~/.config/concise/concise.json.
A write compares the file with the version the preview read. When the file changed in between, the write stops with Configuration changed on disk.
Exit status: 0 on success, 1 when check finds something or validate finds an invalid file, 2 on an error. Errors go to stderr as concise-config: <reason>.
MCP server
tools/mcp-server.mjs is a stdio MCP server with no dependencies. It writes JSON-RPC to stdout and logs to stderr.
| Tool | Writes | Operation |
|---|---|---|
concise_settings_show | no | show |
concise_settings_keys | no | keys |
concise_settings_get | no | get |
concise_settings_edit | with apply | set, unset, add, remove through op |
concise_settings_validate | no | validate |
concise_dictionary | with apply | dict list, add, remove, test through action |
concise_check_text | no | check |
concise_tune | with apply | tune, with paths and texts |
The project directory is the cwd argument, else CLAUDE_PROJECT_DIR, else the server’s working directory. When the working directory is the plugin itself, every tool except concise_settings_keys and concise_dictionary with action: "test" refuses the call until cwd is passed.
- Claude Code starts the server from the plugin’s
.mcp.json. - Codex starts it from
.codex-mcp.json, in the plugin directory, so Codex calls passcwd. host-features.md has the details. To register the server by hand:
codex mcp add concise -- node /path/to/plugins/concise/tools/mcp-server.mjs
claude mcp add concise -- node /path/to/plugins/concise/tools/mcp-server.mjsSkills
concise-config: reads the settings, explains a key, previews a change, and writes it after the user agrees. Also covers dictionary entries andcheck.concise-tune: collects the user’s writing samples, runs the tuner, presents the evidence, suggests dictionary entries, and applies the result after the user agrees.concise-rules: the reference for the checks, the escape hatches, and the confirm flow.
The skills call the CLI, so they work when the MCP server is not connected.
Tuner
tune scans the samples with every pack (preset all) and the dash check, with the dictionary off. It proposes changes only for categories in the target preset: --preset, else the preset in effect. Hits that the allow lists already cover do not count.
| Kind | Samples | Scanned as |
|---|---|---|
docs (default) | Prose files. A directory keeps prose files only. | Prose files |
reply | Chat messages. | Replies |
commit | Commit messages, one per file. | Commit messages |
gh | PR or issue bodies, one per file. | gh bodies |
comments | Source files. A directory keeps code files only. | Code comments |
| Signal in the samples | Change |
|---|---|
| A category fires in 2 or more samples, or at least once per 500 words | Adds the category to features.aiWriting.disablePatterns |
| A phrase category fires 2 or more times, always on the same phrase | Adds the phrase to features.aiWriting.allow |
| A statistical pack with a tunable threshold fires | Sets the threshold in features.aiWriting.options to the nearest value that every sample passes |
A statistical pack has fewer words than its minWords | Lists the pack as needing more words |
| A category fires once in one sample | Leaves it on and lists it under kept |
aiWriting is off and the samples have 300 words or more | Turns aiWriting on |
| Em dashes, while the dash check is on | Turns the dash check off |
| En dashes only, while the dash check is on | Sets features.emDash.enDash to false |
| No dashes in 1,000 words or more, while the dash check is off | Turns the dash check on |
Kind gh | Raises maxPrBodyParagraphs and maxPrBodySentences to the 90th percentile of the samples |
Kind comments | Raises maxCommentLines to the 90th percentile of the comment runs |
Each change comes with its reason and up to 3 quoted examples from the samples. --apply merges the change into the chosen layer: objects merge, lists gain the new items, and other values are replaced.