why codeably?

| | codeably | GitHub Copilot | Cursor | Claude Code | |---|---|---|---|---| | Cost | $0 (your key) | $10/mo | $20/mo | $20/mo | | Works in terminal | ✅ | ❌ | ❌ | ✅ | | Multi-provider | 8 providers | OpenAI only | OpenAI/Anthropic | Anthropic only | | Fully offline | ✅ (Ollama) | ❌ | ❌ | ❌ | | Open source | ✅ MIT | ❌ | ❌ | ❌ |

quickstart

# No install — try it right now
npx codeably

# Or install globally
npm install -g codeably
codeably "your task here"

Requires Node.js 18+. That's it.

First run launches a setup wizard — pick your provider and enter your API key. Saved locally, never shared.

switching providers

Run the setup wizard anytime to switch providers or update your API key:

codeably config

Your key is saved at ~/.codeably/config.json — never leaves your machine.

what it does

codeably "add JWT authentication to the express app"
codeably "find and fix the race condition in payment.js"
codeably "write unit tests for every exported function in utils.js"
codeably "migrate from callbacks to async/await across all files"
codeably "add TypeScript types to all files in src/"
codeably clean                   # scan + remove dead code
codeably review                  # AI code review of git changes
codeably docs                    # generate or update README + JSDoc
codeably ask "what does this error mean?"   # quick answer, no agent
codeably --continue "also add error handling"  # resume last task

free providers

| Provider | Free tier | Speed | Best for | |---|---|---|---| | Groq | 14,400 req/day | ⚡ Fastest | Most tasks | | Gemini | 1,500 req/day | Fast | Long context | | OpenRouter | Free models | Fast | Model variety | | Ollama | Unlimited | Local | Privacy / offline | | Anthropic | $5 credit on signup | Excellent | Best coding quality | | Mistral | Free trial | Fast | European data privacy | | OpenAI | Pay per use | Good | GPT-4o | | OmniRoute | 1.6B tokens/month | Fast | 231+ providers, auto-fallback |

Your API key is saved at ~/.codeably/config.json — never leaves your machine.

terminal chat UI

codeably chat   # or: cb chat

  ╭────────────────────────────────────────────────────────────╮
  │  >/<  codeably chat                                         │
  │  groq  ·  llama-3.3-70b-versatile                          │
  │  type /help for commands                                    │
  ╰────────────────────────────────────────────────────────────╯

  ❯ explain how async/await works in JavaScript

  Async/await is syntactic sugar over Promises...

  ❯ /switch   ← switch provider mid-conversation
  ❯ /save     ← save conversation to file
  ❯ /clear    ← start fresh

⚡ cb shortcut

# macOS / Linux / WSL
bash install-shortcut.sh && source ~/.zshrc

# Windows PowerShell
.\install-shortcut.ps1

# Now just type:
cb "refactor auth.js"
cb clean
cb review
cb ask "what is a closure?"

new in v1.3.1

• codeably ask — quick one-shot question, no agent loop, streams instantly
• --continue — resume the last task: codeably --continue "also add tests"
• --steps N — control max agent steps: codeably --steps 100 "big refactor"
• codeably update — self-update to latest version
• url_fetch tool — agent can now read docs and APIs from the web
• npm_info tool — agent looks up package info before installing
• explain_error tool — agent explains errors before fixing them
• Streaming — agent thoughts stream in real time
• Auto-retry — retries automatically on rate limit (up to 3x with backoff)
• Step counter — see step 4/50 progress in real time
• Version in banner — always know which version you're running
• cb as direct npm bin — works immediately after npm install -g

how it works

OBSERVE  →  list files, detect language, read relevant code
THINK    →  decide what to do and in what order
ACT      →  write / edit / delete files, run commands
VERIFY   →  run tests or build to confirm nothing broke
DONE     →  report what changed in one line

Loops until finished or hits the step limit (default: 50, override with --steps).

33 tools

File I/O

read_file write_file patch_file append_file insert_lines delete_lines copy_file move_file delete_file delete_files_bulk

Directory

make_dir list_files list_dir

Search

search_code find_files grep_replace

Shell

run_command run_script check_port

Analysis

diff_files file_stats count_lines detect_language read_env

Git

git_status git_diff git_log git_commit

Web & Packages (new)

url_fetch npm_info explain_error

Safety & Control

confirm_delete done

safety

Codeably always asks before deleting files:

  ⚠  deletion confirmation required
  reason: unused file, zero imports detected

  files to delete:
    - src/old-utils.js
    - src/deprecated/auth.js

  delete these 2 file(s)? [y/N]:

The agent cannot delete files without your explicit approval.

architecture

codeably/
├── codeably.js              ← CLI entry + all commands
├── config/
│   ├── providers.js         ← 8 providers definitions
│   ├── store.js             ← read/write ~/.codeably/config.json
│   └── setup.js             ← first-run setup wizard
├── runtime/
│   ├── agent.js             ← Observe-Think-Act loop + streaming + retry
│   ├── client.js            ← unified LLM client (streaming + non-streaming)
│   ├── context.js           ← codebase snapshot builder
│   └── memory.js            ← session history (~/.codeably/history.json)
├── tools/
│   └── index.js             ← 33 tools: schemas + executors
├── ui/
│   ├── renderer.js          ← terminal UI (banner, icons, step counter)
│   └── chat.js              ← interactive chat mode
└── tests/
    └── smoke.js             ← smoke test suite

~1000 lines of code. No frameworks. No LangChain.

examples

# Features
codeably "add JWT authentication to the express app"
codeably "add rate limiting — 100 requests per minute per IP"
codeably "add input validation to all API endpoints"
codeably "add a Redis cache layer to the user service"

# Fix bugs
codeably "the login form crashes when email is empty — fix it"
codeably "fix the race condition in the payment processing code"

# Refactor
codeably "split the 300-line UserController into smaller files"
codeably "extract all hardcoded strings into a constants file"
codeably "migrate from callbacks to async/await in api.js"

# Tests
codeably "write unit tests for every exported function in utils.js"
codeably "add integration tests for the auth routes"

# Clean up
codeably clean
codeably "remove all console.log statements from src/"

# Docs & review
codeably review
codeably docs
codeably "add JSDoc comments to all functions in src/api/"

# Git
codeably "commit all current changes with a good commit message"

# Quick questions (no agent loop)
codeably ask "what does Array.flat() do?"
codeably ask "explain the difference between == and ==="
codeably ask "how do I reverse a string in Python?"

# Continue where you left off
codeably "add user authentication"
codeably --continue "now add password reset via email"

run tests

npm test

built with ❤ — bring your own key, own your agent