Manual Mode

Chuck AI. Code manually.

Manual Mode is a small CLI that temporarily blocks AI coding tools so you can spend focused time writing code yourself. Use it when you want to rebuild fundamentals, practice debugging without autocomplete, or keep your programming muscles from getting outsourced. After you manually code, it estimates the water saved and CO2 emissions avoided by the AI sessions you did not need.

It does not delete or modify your AI tools. It installs lightweight command shims, starts timed manual-coding sessions, counts blocked AI attempts, and gives you a Git-based summary of the code you changed.

The v1 metric is Git changed lines, not literal typed lines or keystrokes.

Why Use Manual Mode?

AI coding tools are useful. Constant dependency is expensive.

Manual Mode gives you a deliberate off-switch:

• Block common AI coding CLIs during a timed focus session.
• Keep using your normal terminal and repos.
• Track manual code changed with Git stats.
• Track AI-agent-coded LOC from CLI shims or editor/agent-window integrations.
• See how often you tried to reach for AI.
• See estimated water saved and CO2 emissions avoided when you code manually instead of using AI.
• Stop intentionally with a reason when real work demands it.

It is for developers who want AI as a tool, not a crutch.

Install

Requirements:

• Node.js 20 or newer
• Git
• zsh, bash, or fish

Install from npm:

npm install -g manual-mode
manual-mode setup --yes

Restart your terminal. Then verify the CLI is available:

manual-mode help

Start Your First Session

From inside a Git repo:

manual-mode start 45m

Now try an AI command:

claude

Manual Mode blocks it:

Manual Mode is active for 44m more. Use this session to code manually.

Check status:

manual-mode status

End normally:

manual-mode stop

Stopping prints the completed session report immediately, including changed lines and estimated avoided AI impact.

Override intentionally:

manual-mode stop --reason "production bug"

What Gets Blocked?

Manual Mode installs shims in:

~/.manual-mode/bin

It currently creates shims for:

• codex
• claude
• cursor
• agent
• opencode
• aider
• gemini

The shims are created even if those tools are not installed yet. Later, if you install one of them, Manual Mode still intercepts it as long as ~/.manual-mode/bin appears before the real tool in PATH.

When Manual Mode is inactive or expired, shims forward to the real command and avoid recursively calling themselves.

Duration Examples

manual-mode start 45
manual-mode start 45m
manual-mode start 1h
manual-mode start 1hr
manual-mode start 2hrs
manual-mode start 1d

Reports and History

Manual Mode stores state and history in:

~/.manual-mode/state.json

Show the latest report:

manual-mode report

Show every completed session:

manual-mode report --all

Show the last two completed sessions:

manual-mode report --last 2

Example:

Manual Mode Summary
Duration: 45m
AI attempts blocked: 3

Total:
+128 lines added
+104 substantive lines added
-37 lines removed
6 files changed

Estimated avoided AI impact:
AI sessions avoided: 1.6
Confidence: medium
Basis: 65 median substantive LOC per AI session from 12 AI sessions
Ignored: 2 AI sessions below 10 substantive LOC
Model basis: gpt-5 from recorded AI sessions
Water saved: 16-80 ml estimated
CO2 avoided: 0.3-8 g CO2e estimated

Repos:
frontend
  +90 / -20 / 4 files
backend
  +38 / -17 / 2 files

Manual Mode estimates avoided AI impact from substantive manual LOC, not raw added lines. Blank added lines and simple comment-only additions are ignored for this estimate. Once at least five AI-agent sessions with at least 10 substantive LOC each have been recorded, reports estimate avoided AI sessions from the median substantive LOC per AI session. Smaller positive AI sessions are ignored for calibration so tiny edits do not inflate savings. Water and CO2 savings are calculated from conservative internal per-session ranges for recorded model families, or generic defaults when model data is missing or unknown. These values are estimates, not provider-certified measurements. manual-mode report also shows a cumulative "Manual Savings To Date" total across completed sessions.

Completed sessions are saved under sessions in ~/.manual-mode/state.json, including a final report snapshot. Expired sessions are archived the next time manual-mode status, manual-mode report, or manual-mode start runs.

Estimated AI-Agent-Coded LOC

Manual Mode cannot magically prove whether a line was written by AI or by a human. Instead, it gives you an honest best-effort workflow: AI CLI shims automatically wrap agent runs with a Git baseline, and editor or agent-window extensions can record AI-authored edits directly.

For CLI tools such as codex, claude, cursor, agent, opencode, aider, and gemini, no manual vibe-session command is required. When Manual Mode is inactive, the shim forwards to the real tool and records the Git line delta after that agent process exits.

Editor or agent-window integrations can record activity with:

manual-mode agent record --tool cursor --source extension --lines-added 120 --files-changed 4

You can optionally include the model for more specific report estimates:

manual-mode agent record --tool codex --model gpt-5 --lines-added 120 --files-changed 4

Set a reminder threshold:

manual-mode agent threshold 500

Check progress:

manual-mode agent status

Once estimated AI-agent-coded added lines since your last Manual Mode session reach the threshold, status, report, and agent status remind you to manually code:

Reminder: You have 640 estimated AI-agent-coded lines since your last Manual Mode session.
Start manual practice: manual-mode start 45m

Completing a Manual Mode session resets the reminder window.

manual-mode vibe start|stop|status|threshold still works as a compatibility alias for older workflows, but the intended path is automatic CLI detection or extension-reported agent activity.

An integration that needs an explicit boundary can use:

manual-mode agent start
manual-mode agent stop

Repository Tracking

When you run:

manual-mode start 45m

Manual Mode:

1. Checks whether the current directory is inside a Git repo.
2. If yes, tracks that repo.
3. If no, scans immediate child directories for Git repos.
4. Tracks all found repos without deep recursive scanning.

You can also choose repos explicitly:

manual-mode start 45m --repo ~/frontend --repo ~/backend

For each repo, Manual Mode stores a baseline HEAD, diff snapshot, numstat, and initial untracked file list.

Commands

manual-mode setup [--yes]
manual-mode start <duration> [--repo <path> ...]
manual-mode stop [--reason "production bug"]
manual-mode status
manual-mode report
manual-mode report --all
manual-mode report --last 2
manual-mode agent status
manual-mode agent threshold <lines>
manual-mode agent record --tool <name> --lines-added <count>
manual-mode agent start [--repo <path> ...]
manual-mode agent stop
manual-mode uninstall
manual-mode help

Troubleshooting

manual-mode start says shims are not active

Your current shell does not have ~/.manual-mode/bin early enough in PATH.

Run:

export PATH="$HOME/.manual-mode/bin:$PATH"
hash -r
manual-mode start 45m

If that works, rerun setup and restart your terminal:

manual-mode setup --yes

claude, codex, or agent still opens during Manual Mode

Check which binary your shell is using:

command -v claude
command -v agent

During a protected shell, those should point inside:

~/.manual-mode/bin

If they do not, Manual Mode cannot intercept that command in the current shell.

Why does setup edit shell files?

CLI blocking only works if Manual Mode shims appear before the real AI commands in PATH.

On zsh, setup writes the PATH entry to both ~/.zshrc and ~/.zprofile. On bash, it writes to ~/.bashrc and ~/.bash_profile. On fish, it updates ~/.config/fish/config.fish.

Codex Desktop and Editor Apps

Manual Mode reliably blocks CLI usage, such as the codex command.

Blocking a desktop app or editor chat panel may require an official plugin, hook, or extension API before message submission. A future integration can read ~/.manual-mode/state.json and warn when Manual Mode is active.

Website

Product page:

https://imaresss.github.io/manual-mode/

Source:

site/index.html

Development

Clone the repo and install locally:

npm install
npm link
manual-mode setup --yes

Run tests:

npm test

Preview the npm package:

npm pack --dry-run

License

MIT