codeably

Autonomous coding agent for your terminal
Bring your own API key  ·  30 tools  ·  7 providers  ·  free forever

日本語  ·  中文  ·  한국어

---

npx codeably "add input validation to the login form"
npx codeably "find and remove all dead code"
npx codeably "write tests for src/utils.js"
npx codeably clean
npx codeably review

---

quickstart

No install (try it now)

npx codeably "your task here"

Global install (recommended — faster)

npm install -g codeably
codeably "your task here"

From source

git clone https://github.com/adamyasingh-05/Codeably
cd Codeably
npm install
npm link

Requires Node.js 18+

---

⚡ shortcut — type cb instead of codeably

Save keystrokes with the one-command installer:

macOS / Linux / WSL

# Inside your cloned repo:
bash install-shortcut.sh

# Then reload your shell:
source ~/.zshrc   # or ~/.bashrc

Windows (PowerShell)

.\install-shortcut.ps1
# Then reload:
. $PROFILE

Now just type:

cb "refactor auth.js"
cb clean
cb review
cb config

---

first run

Just type codeably — a setup wizard runs once and saves your config:

  ╭─────────────────────────────────────────────────────╮
  │  >/<  codeably                                       │
  │       autonomous coding agent for your terminal     │
  │       7 providers  30 tools  free forever           │
  ╰─────────────────────────────────────────────────────╯

  First time? Let's get you set up.

  Choose a provider:

  1.  Anthropic   (Claude Sonnet 4 — best for coding)   Free $5 credit on signup
  2.  OpenAI      (GPT-4o)                              Pay per use
  3.  Groq        (Llama 3.3 70B — very fast)           FREE — 14,400 requests/day
  4.  Google      (Gemini 2.0 Flash — 1M context)       FREE — 1,500 requests/day
  5.  Mistral     (Mistral Large — great for code)       Free trial credits
  6.  OpenRouter  (100+ models, one key)                 FREE models available
  7.  Ollama      (local, 100% free, works offline)      FREE forever

  your choice (1-7): _

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

---

free providers

Provider	Free tier	Sign up
Groq	14,400 req/day	console.groq.com
Gemini	1,500 req/day	aistudio.google.com
OpenRouter	Free models (Llama, DeepSeek, Gemini…)	openrouter.ai
Ollama	Unlimited, offline	ollama.com
Anthropic	$5 credit on signup	console.anthropic.com
Mistral	Free trial credits	console.mistral.ai
OpenAI	Pay per use	platform.openai.com

---

commands

codeably "task"     # run a task in the current directory
codeably            # interactive — prompts you for a task
codeably config     # change provider or API key
codeably whoami     # show current provider + model
codeably history    # show recent sessions
codeably clean      # scan + remove dead code (always asks before deleting)
codeably review     # AI code review of recent git changes
codeably docs       # generate or update project documentation
codeably init       # scaffold a new project interactively
codeably help       # show all commands

# With the `cb` shortcut installed:
cb "task"
cb clean
cb review

---

safety

Codeably always asks before deleting files. You'll see:

  ⚠  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]:

Type y to proceed, anything else to cancel. The agent cannot delete files without your explicit approval.

---

how it works

Every task runs through the same loop:

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).

---

30 tools

File I/O

Tool	What it does
read_file	Read file, optionally by line range
write_file	Create or overwrite a file
patch_file	Replace exact string in a file (safe small edits)
append_file	Append to end of a file
insert_lines	Insert content at a specific line number
delete_lines	Remove a range of lines from a file
copy_file	Copy file to a new path
move_file	Move or rename a file
delete_file	Delete a file (requires confirm_delete first)
delete_files_bulk	Delete multiple files (requires confirm_delete first)

Directory

Tool	What it does
make_dir	Create a directory
list_files	Explore directory tree
list_dir	Flat list of a directory with file sizes

Search

Tool	What it does
search_code	Find a pattern across all files
find_files	Find files by name pattern (glob)
grep_replace	Find and replace across multiple files

Shell

Tool	What it does
run_command	Run any shell command
run_script	Write and execute a multi-line bash script
check_port	Check if a port is in use

Analysis

Tool	What it does
diff_files	Show unified diff between two files
file_stats	Size, line count, last modified, checksum
count_lines	Lines of code by file extension
detect_language	Detect project's primary language(s)
read_env	List .env keys without exposing values

Git

Tool	What it does
git_status	Show modified, untracked, staged files
git_diff	Show staged or unstaged changes
git_log	Show recent commit history
git_commit	Stage all and create a commit

Safety & Control

Tool	What it does
confirm_delete	Ask user before any deletion — mandatory
done	Signal task complete with one-line summary

---

architecture

codeably/
├── codeably.js              ← CLI entry + all commands
├── install-shortcut.sh      ← macOS / Linux / WSL shortcut installer
├── install-shortcut.ps1     ← Windows PowerShell shortcut installer
├── bin/
│   └── create-codeably.js  ← npx entry point
├── config/
│   ├── providers.js         ← provider definitions
│   ├── store.js             ← read/write ~/.codeably/config.json
│   └── setup.js             ← first-run setup wizard
├── runtime/
│   ├── agent.js             ← Observe-Think-Act loop + confirm_delete gate
│   ├── client.js            ← unified LLM client (one client, all providers)
│   ├── context.js           ← builds codebase snapshot for the agent
│   └── memory.js            ← session history (~/.codeably/history.json)
├── tools/
│   └── index.js             ← 30 tools: schemas + executors
├── ui/
│   └── renderer.js          ← enhanced terminal UI (banner, icons, color)
├── tests/
│   └── smoke.js             ← 25-check smoke test suite
└── docs/
    ├── assets/
    │   ├── codeably_logo.png
    │   └── codeably_banner.png
    ├── README.ja.md         ← 日本語
    ├── README.zh.md         ← 中文
    └── README.ko.md         ← 한국어

No frameworks. No LangChain. ~900 lines of code total.

---

examples

# Add 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"

# Clean up
codeably clean
codeably "remove all console.log statements from src/"
codeably "migrate from callbacks to async/await in api.js"

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

# Refactor
codeably "split the 300-line UserController into smaller files"
codeably "extract all hardcoded strings into a constants file"

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

# Review & docs
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"

---

run tests

npm test

Runs 25 checks across all 30 tools. No API key required.

---

install shortcut — quick reference

Platform	Command	Result
macOS/Linux/WSL	bash install-shortcut.sh	cb alias in shell
Windows PowerShell	.\install-shortcut.ps1	cb function in profile
Manual (any shell)	alias cb="codeably"	add to your shell rc file

---

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