Codison

A fast, autonomous AI CLI agent that acts as a senior developer inside your repo. It edits code, runs tests, and follows your conventions.

Open source. Built for speed, reliability, and a calm developer experience.

GitHub Quickstart

Core ideas

Speed-first: minimal latency, minimal chatter.
Autonomous: edits → builds → tests → verifies.
Context-aware: learns your style and architecture.
Proactive verification: runs tests/lint before claiming success.
Concise output: CLI-friendly logs, no fluff.
Memory: remembers conventions and project facts.

Requirements

Node.js 18+
Internet connection (for Codison’s AI)

Install

npm i -g codison

npm i -g codison

yarn global add codison

yarn global add codison

pnpm add -g codison

pnpm add -g codison

API Key

Codison requires an API key to work with an AI provider. You can provide either:

OPENAI_API_KEY
GEMINI_API_KEY

Set one of these environment variables before running Codison:

export OPENAI_API_KEY=sk-xxxx
# or
export GEMINI_API_KEY=your-gemini-key

export OPENAI_API_KEY=sk-xxxx# orexport GEMINI_API_KEY=your-gemini-key

Quickstart

Run a non-interactive task from your project root:

codison "Fix bug in auth middleware and add tests"

codison "Fix bug in auth middleware and add tests"

Codison will:

Parse your repo and task.
Edit files with minimal diff churn.
Build & run tests.
Verify and summarize the changes.

CLI options

Codison CLI accepts both flags and positional arguments:

Usage: codison [options] [task]

Options:
  -i, --instruction <string>   Provide the task/instruction text
  -w, --workingDir <string>    Path to project root (default: cwd)
  -h, --help                   Display help

Usage: codison [options] [task]Options:  -i, --instruction <string>   Provide the task/instruction text  -w, --workingDir <string>    Path to project root (default: cwd)  -h, --help                   Display help

Examples

Codison can be used from the CLI (interactive or non‑interactive), in CI, or embedded programmatically in your code. Pick a tab:

# From your project root
codison

# Then type your task when prompted
> Refactor the auth middleware to remove duplicated logic,
> add tests for token refresh, and update docs if needed.

# From your project rootcodison# Then type your task when prompted> Refactor the auth middleware to remove duplicated logic,> add tests for token refresh, and update docs if needed.

Codison will explore the repo, propose edits, run build/tests, iterate until green, and summarize changes.

codison 'Fix flaky login E2E by stabilizing wait conditions and adding retry to token fetch'

codison 'Fix flaky login E2E by stabilizing wait conditions and adding retry to token fetch'

Fire‑and‑forget for well‑scoped tasks. Perfect for scripts and one‑liners.

name: codison

on: [pull_request]

jobs:
  codison:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm i -g codison
      - run: codison 'Review this PR: run tests, suggest safer diff if needed, and output summary'
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

name: codisonon: [pull_request]jobs:  codison:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4      - uses: actions/setup-node@v4        with:          node-version: 20      - run: npm i -g codison      - run: codison 'Review this PR: run tests, suggest safer diff if needed, and output summary'        env:          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

Runs on PRs to test/verify and produce a summary comment/log.

import { Codison } from 'codison';

const agent = new Codison({ projectRoot });
return agent.runNonInteractive('Add input validation to /api/users and unit tests');

import { Codison } from 'codison';const agent = new Codison({ projectRoot });return agent.runNonInteractive('Add input validation to /api/users and unit tests');

Embed Codison inside build tools, CLIs, or server scripts.

Validate and normalize descriptions in a doc‑generator pipeline:

import { Codison } from 'codison';

/**
 * Checks that JSDoc/annotations are in English, concise, and consistent.
 * Fixes minor issues and updates docs/tests accordingly.
 */
export async function lintDocsWithCodison() {
  const agent = new Codison({ projectRoot: process.cwd() });
  const result = await agent.runNonInteractive([
    'Scan annotations (TS/JS) for description quality: English language, tone consistency,',
    'and naming alignment with code. Where trivial, fix typos/grammar and update docs.',
    'Run build and tests to verify no regressions.'
  ].join(' '));
  return result;
}

import { Codison } from 'codison';/** * Checks that JSDoc/annotations are in English, concise, and consistent. * Fixes minor issues and updates docs/tests accordingly. */export async function lintDocsWithCodison() {  const agent = new Codison({ projectRoot: process.cwd() });  const result = await agent.runNonInteractive([    'Scan annotations (TS/JS) for description quality: English language, tone consistency,',    'and naming alignment with code. Where trivial, fix typos/grammar and update docs.',    'Run build and tests to verify no regressions.'  ].join(' '));  return result;}

Philosophy

Codison aims to be a trustworthy teammate in your CLI: respectful of your workflows, explicit about changes and risks, and focused on shipping—not showmanship.