Agentic CLI Coding

a code-editing toolkit for agents. provides the oce command, which wraps reads, searches, edits, validation, formatting, backups, and multi-file transactions behind one predictable interface that always validates after writing and rolls back on syntax failure.

this skill exists because raw sed, awk, and perl -i are too sharp for autonomous use. they apply changes silently, give regex-style false matches, leave no audit trail, and can't roll back. oce keeps the speed of cli editing while adding the safety rails an agent needs.

---

intent

use this skill for any task that involves reading, understanding, searching, or modifying source code in a project across javascript, typescript, vue, react, node, python, go, ruby, php, java, rust, c/c++, shell scripts, json, yaml, html, css, sql, and markdown. trigger whenever the user asks to fix a bug, add a feature, refactor, rename, restructure, search a codebase, locate a function or symbol, apply a patch, modify configuration, or make any multi-file change. use when the user references files by path or name and wants something done to them, when reviewing or auditing code, or when planning an edit before making it. prefer oce over raw sed/awk/perl -i for any persistent edit; those are read-only here.

---

inputs

required:

• bash 4.0 or later (check with bash --version)
• write access to current working directory (skill creates .oce/ for backups and transaction state)
• core tools (automatically checked by oce doctor): node, patch, diff, grep, acorn

optional but recommended for full feature set:

• prettier (javascript/typescript formatting)
• black (python formatting)
• gofmt (go formatting)
• rustfmt (rust formatting)
• tsc locally installed (typescript ast operations beyond js-compatible subset)

external connections:

• none required; this skill operates entirely on local filesystem

environment setup:

• skill location: <skill-path> refers to where the skill is installed (typically /home/agent/.skills/agentic-cli-coding or similar)
• invocation: set alias once per session with alias oce="bash <skill-path>/scripts/oce.sh" (recommended for agentic use)
• alternative invocation: bash <skill-path>/scripts/oce.sh <subcommand> (works without setup)
• persistent installation: bash <skill-path>/scripts/install.sh adds wrapper to path

---

procedure

step 0: verify setup (run once per session)

oce doctor

exit code 0 with "setup ok" means toolkit is ready. all core tools must be present. missing optional tools only affect formatting for that language; editing still works.

if "oce: command not found" appears, the alias wasn't set. use direct invocation instead: bash <skill-path>/scripts/oce.sh <subcommand>.

step 1: orient (understand the codebase before editing)

discover project structure and locate relevant code:

oce tree --depth 2                      # outputs: nested tree of project layout
oce find "<keyword>" --type <lang>      # outputs: list of files matching keyword and language type
oce ast symbols path/to/file.js         # outputs: functions, classes, exports in file

input: keyword (string to search), file path (string), language type (js, ts, py, go, etc.)

output: file paths and/or symbol names matching the search

note: do not skip orientation. repository conventions vary; assumptions break codebases.

step 2: read (load exact context needed for editing)

fetch file content with surrounding context:

oce read src/server.js --around "handleAuth" --context 20
oce grep-context "TODO" src/server.js -c 5
oce read src/auth.js --lines 45:120

input: file path (string), anchor text or line range (string or int:int), context window (integer, default 5)

output: file content with line numbers, context highlighted

note: read enough surrounding context to predict what your edit will affect. the cheapest break is editing a function in isolation without seeing its callers.

step 3: plan (state changes before executing)

for non-trivial edits, state the plan explicitly before running any edit command:

• what is being added (new lines, new files)
• what is being removed (deletions, deprecations)
• what is being modified (in-place changes)
• what is at risk (files that touch same symbols, public apis, tests)
• what will be validated (which files need to compile, which tests should pass)

for multi-file changes, start a transaction:

TXN=$(oce transaction begin)

input: (none; creates unique transaction id)

output: transaction id (stored in .oce/transactions/)

then pass --txn "$TXN" to every subsequent edit command. commit (validates everything atomically) or rollback (restores every file) at the end.

step 4: execute (apply the correct edit tool, then verify)

choose edit command based on change type:

tiny surgical changes: exact-string replace with oce replace

oce replace src/server.js \
  --old "return data;" \
  --new "return sanitize(data);"

input: file path, old text (literal match), new text

output: number of replacements made, backup location

insert code at anchor: oce insert with line or text anchor

oce insert src/server.js --before-match "// END ROUTES" --content-file /tmp/new_route.js
oce insert src/server.js --line 42 --content "new line here"

input: file path, anchor (text match or line number), new content (inline or file)

output: insertion point, backup location

remove lines: oce delete by line range or match

oce delete src/server.js --lines 10:15
oce delete src/server.js --match "TODO.*\n"

input: file path, line range or regex match

output: lines deleted, backup location

multi-line precision: write unified diff and apply with oce patch apply

cat > /tmp/fix.patch <<'EOF'
--- a/src/auth.js
+++ b/src/auth.js
@@ -12,6 +12,10 @@
 function authenticate(req) {
+  if (!req.headers.authorization) {
+    throw new Error('Missing auth header');
+  }
   const token = req.headers.authorization.split(' ')[1];
EOF

oce patch apply /tmp/fix.patch

input: unified diff file (text)

output: files patched, backup locations, validation results

rename js/jsx identifier: scope-aware rename with oce ast rename

oce ast rename src/auth.js --old "validateToken" --new "verifyToken"

input: file path, old identifier name, new identifier name

output: number of references renamed, backup location

note: js/jsx only; walks ast and renames only real references, not strings or comments.

replace function/class body: oce ast replace-symbol

oce ast replace-symbol src/auth.js --symbol "authenticate" --body "$(cat /tmp/new_body.js)"

input: file path, symbol name (function or class), new body text

output: symbol replaced, backup location

new file or full rewrite: oce write

oce write path/to/newfile.js --content "$(cat /tmp/content.js)"
oce write src/config.json --content '{"debug":true}'

input: file path, content (inline or stdin)

output: file written, backup of prior version if file existed

multi-file transaction: chain any edit commands with --txn "$TXN"

TXN=$(oce transaction begin)
oce replace src/auth.js --old "validateToken" --new "verifyToken" --all --txn "$TXN"
oce replace src/api.js  --old "validateToken" --new "verifyToken" --all --txn "$TXN"
oce transaction validate "$TXN"
oce transaction commit "$TXN"   # or rollback "$TXN" if anything looks wrong

input: transaction id (string)

output: per-command outputs (replacements made, files affected), final validation report

after every edit, validate and verify:

oce diff src/server.js          # compare current vs. most recent backup
oce validate src/server.js      # syntax check (auto-runs after edit, but you can re-check)

input: file path

output: diff/validation result

auto-validation catches syntax errors and rolls back on failure. you don't need to re-validate manually, but you should oce diff to confirm the change matches your intent.

step 5: recover (if needed)

if an edit broke something, backups are auto-created before every destructive operation:

oce backup list src/server.js           # see all snapshots for that file
oce backup diff src/server.js           # compare current vs. most recent backup
oce backup restore src/server.js        # restore most recent backup
oce backup restore src/server.js --at 3 # restore 4th-most-recent (0-indexed)
oce backup clean 30                     # remove backups older than 30 days

input: file path, backup index (optional), age threshold in days (optional)

output: backup restored, list of snapshots, or cleanup summary

backups live in .oce/backups/ in the workspace.

---

decision points

setup method: if the skill is used once, use direct invocation bash <skill-path>/scripts/oce.sh <subcommand>. if used repeatedly in same session, set alias once with alias oce="bash <skill-path>/scripts/oce.sh". if used across sessions or by multiple agents, run bash <skill-path>/scripts/install.sh for persistent installation.

orientation required: if you "know" where the code is from training data, still run oce tree and oce find. repository conventions vary; skip orientation at your peril.

read context: if you're changing a function, always read with --context 20 or higher. if you're changing a single line in isolation, --context 5 is acceptable.

edit tool choice: if the change is exact-string and single-line, use oce replace. if it spans multiple lines and you have a unified diff, use oce patch apply. if it's multi-line but no diff handy, use oce insert or oce delete in sequence or write a diff first. if it's a js/jsx identifier rename, use oce ast rename. if it's an entire function body, use oce ast replace-symbol. if you're creating a new file, use oce write.

transaction required: if editing one file, no transaction needed. if editing two or more files for a single logical change, use TXN=$(oce transaction begin) and --txn "$TXN" on every edit. commit or rollback atomically.

non-unique match: if oce replace --old "X" fails with "ambiguous match", either make --old more specific (add surrounding context like indent or closing brace) or pass --all if you genuinely want every occurrence changed.

formatting: oce format only runs if the formatter is installed on the local system. check oce doctor output if you care about canonical formatting. formatting is optional; validation is not.

binary files: if oce refuses to edit a file, it's likely binary. do not attempt to bypass with env vars or override flags. reconsider the approach.

edge case: rate limits: not applicable; this skill is local-only.

edge case: auth expiry: not applicable; no external api connections.

edge case: empty result sets: if oce find returns zero matches, the keyword or language type was wrong or the code doesn't exist. re-read the codebase with oce tree and try again.

edge case: network timeout: not applicable; local filesystem only.

edge case: syntax validation failure: if a file fails validation after edit, oce automatically rolls back the change and reports the syntax error. check the error message, fix the logic, and try again.

edge case: patch apply failure: if oce patch apply fails with "patch does not apply cleanly", the file has changed since you wrote the diff. re-read the current file, update the diff, and try again.

---

output contract

success indicators:

• oce commands exit with code 0 on success, non-zero on error
• human-readable output goes to stdout (default)
• errors go to stderr
• all edit commands produce a backup file in .oce/backups/<filename>.<timestamp> before destructive operation
• all edit commands output line count or match count (e.g., "replaced 3 occurrences", "inserted 1 block")
• transaction operations output transaction id on success
• --json flag produces single-line json object on stdout conforming to schema in references/json-schema.md

backup storage:

• location: .oce/backups/ inside current working directory
• format: gzip-compressed copies of pre-edit file state
• naming: <filename>.<iso8601-timestamp>.gz

audit trail:

• location: .oce/edit.log inside current working directory
• format: newline-delimited json, one record per edit
• retention: permanent (user must delete manually or run oce backup clean)

validation output:

• format: per-language syntax check results (e.g., "node --check" for js, "python -m py_compile" for python)
• rollback on failure: yes; file is automatically restored to pre-edit state if validation fails

file state after successful edit:

• file is modified in-place
• backup of prior state exists in .oce/backups/
• syntax is validated; if broken, edit is rolled back
• formatting is not applied unless oce format is explicitly called

transaction state:

• location: .oce/transactions/<txn-id>/ with per-file backup copies
• validation: atomic; all files validated together
• commit: all changes persisted, backups retained
• rollback: all changes reverted to pre-transaction state, transaction deleted

---

outcome signal

the user knows the skill worked when:

• oce doctor outputs "setup ok" and lists all available tools
• oce tree --depth 2 outputs a readable tree of the project structure
• oce find <keyword> outputs file paths containing the keyword
• oce read <file> outputs the file content with correct syntax highlighting and line numbers
• oce replace/oce insert/oce delete/oce patch apply output a message like "replaced X occurrences" or "inserted Y lines" and exit with code 0
• oce diff <file> outputs a readable unified diff showing exactly what changed
• oce backup list <file> outputs a list of available snapshots
• oce backup restore <file> restores the file and outputs confirmation
• oce transaction commit outputs success with no rollback
• no file is corrupted or lost; all prior states are backed up in .oce/backups/
• the edited code passes syntax validation and runs without "parse error" or "syntax error" messages
• for multi-file changes, all files are in a consistent state (all committed or all rolled back, never partial)

---

references and edge cases

full documentation lives in the skill's reference directory:

• references/json-schema.md exact json output schema for every command; read when chaining or parsing programmatically
• references/workflows.md worked examples: bug fix flow, feature add flow, refactor flow, dependency upgrade flow, vue/react component editing
• references/language-support.md per-language validator and formatter matrix; what works without extra installs, what needs local tooling
• references/troubleshooting.md symptom to cause to fix table for common failures

storage and state:

• skill writes nothing to home directory
• all state lives in .oce/ inside current working directory
• you can safely add .oce/ to .gitignore
• to clean up backups older than 30 days, run oce backup clean 30

anti-patterns to avoid:

• do not use sed -i, awk redirected to same file, or perl -i; use oce replace or oce patch instead
• do not use oce write for small edits; use replace, patch, or insert instead
• do not pass non-unique --old to oce replace without --all; command will fail with "ambiguous match" error
• do not edit multiple files without a transaction; file 2 failure leaves file 1 inconsistent
• do not skip oce diff after non-trivial edits; catches logic errors auto-validation misses
• do not assume formatter ran; check oce doctor if you care
• do not edit binary files; oce refuses by design
• do not invent file paths; confirm with oce read or oce tree first

one-line summary: oce <verb> <file> [options] every verb backs up first, validates after, and rolls back on syntax failure. use transactions for multi-file changes. read before you write. plan before you execute.

---

credits: original by encryptshawn on clawhub. enriched per implexa standards.