Coding Friend

💡 If you have problems with CF, use /cf-help to get help or ask in the GitHub Discussions.

Coding Friend adds skills, agents, and hooks to the tools you already use. You get plan → implement → review → commit, with project knowledge in docs/ and learning notes in ~/.coding-friend/learn/. A memory system runs underneath, along with useful hooks and mechanisms to protect your privacy and security.

🤝 Supported Tools

Coding Friend installs on the host you already use.

% = Claude is a baseline with all skills, agents, hooks. Some are Claude only: statusline, session save/restore (/cf-session), and task tracking. Other hosts ship their own equivalents, so they are not counted.

📦 Install

🤖 Automatic Installation (Recommended)

Copy and paste this prompt into your AI agent — it will read the documentation and set up everything automatically:

📋 Manual Installation

You need Node 20+ and a supported host.

Via CLI (Recommended)

npm i -g coding-friend-cli
# If `cf` is taken, use `cdf`

cf install               # Claude Code (default)
cf install --agent codex # or 'omp', 'agy', 'devin'

cf init                  # per project: docs/, .coding-friend/config.json
cf update                # later: pull the newest plugin

# Need help?
cf help

# Get Started in any project
cf init

Scope with --user | --project | --local. Host aliases: --codex / --omp / --agy / --devin. Then use /cf-help inside your agent to ask anything about CF.

Via Plugin Manager

plugin marketplace add dinhanhthi/coding-friend
plugin install coding-friend@coding-friend-marketplace

Devin CLI (beta): devin plugins install dinhanhthi/coding-friend#plugin-devin installs the generated plugin-devin/ directly. Inside Devin, invoke skills bare or namespaced — /cf-plan or /coding-friend:cf-plan.

After cf init or working with CF, a folder docs/ is created inside your project with nested folders for plans, memory, research, reviews,... and more.

✨ Features

Skills are slash commands (/cf-*) or auto-invoked when a matching situation appears. Settings that live in config.json — run cf config and follow the instructions there. To extend a built-in skill, see Custom Guides.

🔁 Workflow

You plan, implement, review, commit, then ship. Bugs loop through /cf-fix and cf-sys-debug.

🗺️ Plan & build

• /cf-plan (source) — Brainstorms with you, then writes a phased plan under docs/plans/<plan-name>/ (plus brief.md with the original request and Q&A in normal/hard mode). Under the hood: cf-explorer maps the repo, cf-planner compares approaches, then cf-implementer runs each task. Each phase stays reviewable (at most 15 files) without over-splitting (fewest phases that fit, normally 3+ tasks each), so reviews stay fast and cheap. Available modes:

  • (none) — normal: full workflow, writes the plan file
  • --fast / --quick — skip discovery and the planner; plan stays in chat, no file. If the plan turns multi-phase it switches to normal and writes the file. Combined with autopilot (--auto or planAuto), the file is always written
  • --hard — extra discovery plus rollback planning
  • --auto — after approval, run every phase (review, fix Critical/Important, commit) with no prompts; combines with any mode. Also on when config planAuto: true unless --no-auto
  • --no-auto — force autopilot off for this run, even if planAuto: true
  • --commit-per-task — with autopilot, commit each task as phase N/M task i/K <title> and review once per phase over those commits; [parallel] phases run sequentially. Also on when config planCommitPerTask: true
  • --no-commit-per-task — force commit-per-task off for this run, even if planCommitPerTask: true
  • --inline / --no-file — plan in chat only, no file; cannot combine with autopilot (--auto or planAuto)
  • --model <alias> — pin cf-planner (opus / sonnet / haiku / fable); ignored in fast
  • --gui / --human — also write a human overview doc (off by default). To turn that doc on for every run, use cf config
  • --add-tests / --tdd — not a plan mode; forwarded to every cf-implementer so each task uses TDD. Without it, implementers write code with no new tests

  Example output:

  Progress
  
  | Status         | Phase             | Tasks   |
  | -------------- | ----------------- | ------- |
  | ✅ DONE        | Phase 1: Teardown | 3 tasks |
  | 🔄 IN PROGRESS | Phase 4: Content  | 6 tasks |
  | ⬜ TODO        | Phase 5: Merge    | 1 task  |
  
  #### Phase 1 [sequential]
  

• /cf-plan-resume (source) — Reloads a saved plan and its context file, skips DONE tasks, re-runs the rest via the same execute protocol. If the plan has auto: true and an AUTOPILOT section, it continues in autopilot, honoring frontmatter commitPerTask: true; --commit-per-task / --no-commit-per-task override it.

• /cf-plan-review (source) — Reviews a saved plan folder with a fresh in-session reviewer before you implement it; --codex / --gemini / --claude / --cursor / --grok add external reviewers in parallel and merge. --fix (--inline) applies Critical/Important findings immediately. Writes review.md next to the plan and, without --fix, offers to apply Critical/Important findings.

• /cf-advise (source) — Interviews one question at a time, then a verdict-first recommendation with pitfalls and ranked alternatives. Never writes code or a plan. Flags: --quick / --fast (2–3 questions), --save (write to docs/memory/decisions/).

• /cf-design (beta) (source) — Makes new or changed UI match the project's existing look. The first word of the argument picks the mode (empty → it asks which one):

  • scan [path] — read existing UI files, extract colors / type / spacing / components, write docs/DESIGN.md
  • [description] — implement new UI from that description, using docs/DESIGN.md (or a fresh scan) as the base
  • modify [what] -- [how] — change one element and keep it consistent with the rest of the project

• /cf-showcase (source) — Builds an intro video (mp4) or poster (png / pdf / html) from the project's real content into docs/showcase/. The agent invents the concept itself (no fixed scene order, scene types or style) and only asks practical questions: length, language, aspect or size, output format, what to emphasize, audio. --video / --poster skip the format question. Video is 30s by default; above 90s it warns about file size and render time, then lets you decide. --default skips the questions and uses your saved defaults (showcase in config, or built-ins); it still shows the concept first. Without it, the skill offers to save your answers as defaults for this project or all projects. You can also edit them with cf config or the cf init menu.

• /cf-optimize (source) — Detects available profilers, measures a baseline, changes one thing, re-measures, compares.

🐛 Fix & debug

• /cf-fix (source) — Reproduces the bug, searches past bug docs, explores, fixes, verifies, then reviews. Escalates hard bugs to cf-sys-debug. --add-tests (or --tdd) writes a failing test first when none exists.

  Example output:

  > ✨ **CODING FRIEND** → /cf-fix activated
  
  Root cause:   [what was wrong, file:line]
  Fix:          [what changed, file:line]
  Confirmed:    [evidence or test that proves the fix]
  Tests:        [pass/fail count, regression test location]
  Status: DONE
  

• cf-sys-debug (source) — Four phases: state a file:line hypothesis before touching code, test it, apply a regression-guarded fix, write a bug doc. Auto-invoked for recurring or unclear bugs.

• cf-tdd (source) — Auto-loaded before production code. Direct mode (default) writes no new tests. TDD mode is --add-tests or --tdd, or tdd: true via cf config. --auto then reviews, fixes Critical/Important, and commits.

• cf-verification (source) — Auto-invoked after code changes. Runs tests / build / lint, shows the output, and blocks a "done" claim without evidence.

🚀 Review & ship

• /cf-review (source) — Snapshots the diff and hands it to cf-reviewer, which checks all five layers: project rules, plan alignment, correctness, security, tests.

  • Depth — auto from change size, or force with --quick / --deep:
    • TRIVIAL — no reviewer: ≤2 files and ≤20 lines, no sensitive paths, only a secrets check (skipped when you pass --quick / --deep)
    • QUICK / STANDARD — 1 reviewer
    • DEEP — 2 reviewers (cf-reviewer-security joins in parallel)
  • External reviewers (opt-in, run in parallel, merged into the same report):
    • --with-codex / --codex, --claude, --gemini, --cursor, --grok
    • --out — write a /cf-review-out prompt instead (not with the flags above)
    • Codex on by default: cf config
  • Fix & commit:
    • --fix — apply Critical/Important findings, then re-review (up to review.maxRounds, default 5)
    • --commit — implies --fix; commits only the reviewed paths once clean, after a secret scan; stops on a pre-commit hook failure
    • --no-fix / --no-commit — force off; config review.fix / review.commit make --fix / --commit the default (/cf-plan, /cf-tdd autopilot and /cf-commit pass --no-fix); unless you typed /cf-review (e.g. after /cf-fix / /cf-optimize), a config-driven commit is skipped when the tree has paths this session did not touch
    • Neither works with a commit-range target or --out
  • Report — always ends with Review status: COMPLETE | PARTIAL | FAILED
    • COMPLETE = full coverage, not "no findings"
    • PARTIAL / FAILED stops an autopilot commit
  • Timeouts:
    • review.nativeTimeout (600s) — soft budget for in-session reviewers
    • review.agentTimeout (300s) — hard limit on each external reviewer
  • Specialists — one generalist is a trade-off, not a free win. cf-reviewer-plan, -quality, -tests, -rules, and -reducer stay directly callable when a layer deserves its own pass.

  Example output:

  🚨 Critical
  - None.
  
  ⚠️ Important
  - None.
  
  💡 Suggestions
  - None.
  
  📋 Summary
  No blocking issues found. You're clear to commit.
  Review status: COMPLETE
  

• /cf-review-out (source) — Writes a self-contained prompt + diff to docs/reviews/ for any external AI or a human.

• /cf-review-in (source) — Reads that result file, presents findings, offers to fix.

• /cf-commit (source) — Analyzes the diff, soft-review check, conventional commit focused on why.

• /cf-ship (source) — Verify → commit → push → PR. --dry-run simulates and does not commit, push, or open a PR. Custom Before guides run first (for example a version bump).

💡 Knowledge

• /cf-ask (source) — Explores the codebase (cf-explorer), answers a focused question, saves the Q&A to docs/memory/.
• /cf-scan (source) — Token-heavy project scan; writes architecture, conventions, and stack into memory (updates, does not duplicate).
• /cf-remember (source) — Extracts conversation knowledge into docs/memory/ (bugs, decisions, conventions, features) for later AI recall. Also auto-invoked.
• /cf-learn (source) — Writes educational notes for you (default ~/.coding-friend/learn/). Host with cf learn host or share with cf mcp. Output, language, and related settings: cf config. Run cf learn host and you get a site like this:
• /cf-teach (source) — Conversational story of what happened and why. Writes under docs/learn by default (not the same folder as /cf-learn). Language and output: cf config.
• /cf-research (source) — Parallel web / subagent research → docs/research/. Does not plan or build.

📌 Context & session

• /cf-session (beta) (source) — Claude only. Saves the session to docs/sessions/ so you can restore it on another machine.
• /cf-checkpoint (source) — Writes a resume snapshot (goal, decisions, next steps) to docs/context/checkpoints/.
• /cf-checkpoint-from (source) — Loads that snapshot into a fresh chat, then does the rest of the message. --recap also prints a short summary of the restored context.
• /cf-warm (source) — Reads git history since you were away, groups it by topic, writes docs/warm/. --user <name> (else git config user.name), --n-commits <N> (default 10).
• /cf-later (source) — Saves a task you want to defer to docs/later/; on Claude Code it runs in a separate subagent, so your current chat stays clean. Pick it up later with /cf-later-do.
• /cf-later-do (source) — Lists docs/later/ items, you pick one, routes to /cf-fix or /cf-plan, deletes the file only after the fix is verified.

❓ Help

• /cf-help (source) — Ask anything about Coding Friend: skills, flags, agents, hooks, CLI, config, memory, hosts. Also auto-invoked when you ask about the toolkit itself.

🧠 Memory

Every session starts from scratch. CF Memory is persistent, searchable project knowledge. Markdown in docs/memory/ is the source of truth. Three search tiers degrade gracefully (SQLite → MiniSearch → grep). Use it from other LLM tools via the MCP server (cf mcp). Run cf config for tier, embeddings, and capture.

✅ Auto-approve

Permission gate for Codex, Antigravity and Devin that auto-approves safe tool calls and working-dir edits and blocks destructive commands. Deterministic rules only, no LLM. Anything the rules do not cover goes back to the host's native approval prompt. Run cf config.

Claude Code and omp: Coding Friend does not add an auto-approve hook. Use their native modes instead: Claude Code auto / acceptEdits / sandboxed Bash, omp yolo (its default).

• Rule-Based Gate: Instant pattern matching — read-only tools auto-approved, destructive commands blocked.
• Working-Dir Edits: File edits inside your project directory are auto-approved.
• Test Runners: npm test, pnpm exec playwright test, pytest, go test, cargo test, mvn test, rspec and friends are always auto-approved, in every language — including piped and chained forms like npm test 2>&1 | tail -50, as long as every other segment is safe too. On Devin, re-gate them with autoApproveIgnore.
• Native Fallback: Unknown tools and commands get no Coding Friend decision. Codex and Devin show their native approval prompt; Antigravity asks.

You can extend the Bash allow list in config:

{
  "autoApprove": true,
  // extra command prefixes to auto-approve. Merged across global + local
  "autoApproveAllowExtra": ["cargo check", "terraform plan"],
  // Devin only: leave these commands to Devin's native prompt.
  // this is also how you re-gate test runners
  "autoApproveIgnore": ["cargo test", "cargo build"]
}

⚠️ Not 100% safe: CF auto-approve is an additional layer that helps reduce prompts, but it doesn't guarantee 100% safety. You can still trigger unsafe actions if you use the wrong command.

🛡️ Security

Layered prompt-injection defense. Three layers: isolation, extraction, then alert. Fetched content is data, never instructions.

• Isolation: External content flagged as untrusted data — never treated as instructions.
• Extraction: Only facts and information extracted — embedded commands discarded.
• Alert: Suspicious content flagged to user — prompt injection attempts exposed.

📟 Statusline

Claude only. Run cf statusline to install the renderer.

🧭 Agents

Skills dispatch agents as subagents that run in their own context.

📘 Custom Guides

Extend a built-in skill without editing the plugin. When that skill runs, CF loads your guide (if one exists) and applies its sections: ## Before before the first step, ## Rules throughout, ## After after the last step. Sections are optional — include only what you need.

cf guide create cf-commit   # scaffolds the local file
cf guide list               # local guides in this project

cf guide create writes a project file. The skill name must match a built-in skill (cf-commit, cf-plan, …). It will not overwrite an existing guide.

Local and global are not merged — if the local file exists, the global one is ignored. The loader resolves the path from the git project root, so it still works if your shell is in a subdirectory.

Example — .coding-friend/skills/cf-commit-custom/SKILL.md:

## Before

- Check branch naming convention (must match `feat/XX-*` or `fix/XX-*`)

## Rules

- Always include the JIRA ticket from the branch name in the commit subject

## After

- Run tests if the commit type is `feat:` or `fix:`

The next time you run /cf-commit, that guide is loaded. No /clear needed.

⚙️ Config

You have two config files. Global is ~/.coding-friend/config.json. Project is .coding-friend/config.json — local overrides global at the same top-level keys.

// Some examples
{
  "language": "en",
  "docsDir": "docs",
  "tdd": false,
  "planAuto": false,
  "planCommitPerTask": false,
  "autoApprove": false,
  "review": {
    "withCodex": false,
    "maxRounds": 5
  },
  "memory": {
    "autoCapture": false
  },
  "learn": {
    "outputDir": "~/.coding-friend/learn"
  },
  "showcase": {
    "video": {
      "length": "auto",
      "aspect": "16:9",
      "audio": true,
      "languages": ["en"]
    },
    "poster": {
      "size": "1200x630",
      "formats": ["png"],
      "languages": ["en"]
    }
  }
}

Learn notes default to ~/.coding-friend/learn/ (learn.outputDir is configurable). docsDir is for plans, memory, and research — not the default learn output.

memory (MemoryConfig) keys:

• tier — "auto", "full", "lite", or "markdown".
• embedding — object with provider ("transformers" or "ollama"), model, and ollamaUrl.
• autoCapture — boolean. Save session context on PreCompact.
• autoStart — boolean. Start the memory daemon when the MCP server connects.

List gitignore-style paths in .coding-friend/ignore so scout-block skips them. A global ~/.coding-friend/ignore applies too; local overrides global. Use !pattern to unblock a default (e.g. !vendor) or, in the local file, a pattern from the global file; to unblock a custom pattern, delete its line.