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.

• /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
    • 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-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 that auto-approves safe tool calls and working-dir edits. Unknown tools defer to Claude's native permission flow / auto mode unless you opt in to the LLM classifier via autoApproveLLM. Run cf config.

• Rule-Based Gate: Instant pattern matching — read-only tools auto-approved, destructive commands blocked.
• Working-Dir Edits: File edits (Write/Edit) 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. Re-gate them with autoApproveIgnore.
• LLM Classifier: Opt-in via autoApproveLLM (default false). When off, unknown tools emit no hook decision and defer to Claude's native permission flow / auto mode. When on, CF shells out to claude --print --model sonnet. Claude only — Codex already has Smart Approvals / --approve-for-me, AGY remembers approvals per chat; spawning those models from a hook would deadlock or race native. Grok / Cursor have no CF hook adapter.

You can extend the Bash allow/deny lists in config:

{
  "autoApprove": true,
  // extra command prefixes to auto-approve. Merged across global + local
  "autoApproveAllowExtra": ["cargo check", "terraform plan"],
  // use below setting to bypass CF auto-approve and let Claude Code handle them.
  // this is also how you re-gate test runners
  "autoApproveIgnore": ["cargo test", "cargo build"],
  // opt-in Sonnet classifier for unknown tools (default: defer to Claude native)
  "autoApproveLLM": false
}

⚠️ 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 or if the LLM classifier (when enabled) makes a mistake.

🛡️ 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,
  "autoApproveLLM": false,
  "review": {
    "withCodex": false,
    "maxRounds": 5
  },
  "memory": {
    "autoCapture": false
  },
  "learn": {
    "outputDir": "~/.coding-friend/learn"
  }
}

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.