scai

# ⚙️ scai — Smart Commit AI ✨ > AI-powered CLI tool for commit messages **and** pull request reviews — using local models. **scai** is your AI pair‑programmer in the terminal. Focus on coding while scai: - 💬 **Suggests intelligent Git commit messages** based on your staged diff - 🤖 **Reviews open pull requests** and provides AI‑driven feedback (BETA) - 📝 **Generates comments for multiple files** while you keep coding - 📜 Auto‑updates your changelog - 🔍 (ALPHA) Search & ask questions across your codebase - 🔐 100% local — no API keys, no cloud, no telemetry --- ## 🚀 Features - ⚡ Powered by open-source models (e.g. `llama3`, `codellama`) - 🔍 Full-text indexing & semantic search (ALPHA) - 🛠️ Built with Node.js and TypeScript - ✅ Easily configurable via CLI or global flags --- ## ❤️ Why Local AI? **Your code stays yours.** scai runs entirely on your machine and doesn't require cloud APIs or API keys. That means: - ✅ **Privacy-first**: no telemetry, no server round-trips - ✅ **EU & GDPR-friendly**: designed with compliance in mind - ✅ **Developer control**: full transparency and override options - ✅ **Offline support**: works even without an internet connection --- ## 📦 Installation 1. **Install Ollama (for local models)** - macOS: `brew install ollama` - Windows: [Download here](https://ollama.com/download) - Start Ollama after installing. 2. **Install scai globally:** ```bash npm install -g scai ``` 3. **Initialize models:** ```bash scai init ``` ## ✨ AI Code Review, Powered by Your Terminal No more struggling to write pull request descriptions by hand. `scai git review` automatically generates a rich summary of your changes, complete with context, suggestions, and rationale. > ⚠️ These features are in **beta** — feedback welcome! Ping [@ticcr](https://bsky.app/profile/ticcr.xyz) on Bluesky — I'd love to hear your thoughts! --- ### 🔑 Setting Up Authentication (Required) To interact with GitHub and create pull requests, `scai` needs a personal access token with **repo** permissions. 1. **Create your GitHub Access Token** Follow this link to generate a token: [https://github.com/settings/personal-access-tokens](https://github.com/settings/personal-access-tokens) Make sure you enable at least: * `repo` (Full control of private repositories) * `workflow` (If you want PRs to trigger CI) 2. **Set the token in scai:** ```bash scai auth set ``` This stores your token locally in a secure config file. You can inspect the setup at any time: ```bash scai auth check ``` 3. **Set the index dir:** ```bash scai index set /path/to/repo ``` This is the repo from which scai will look up pull requests that can be reviewed. --- ## ⚒️ Usage Overview ### 🧠 How to Use `scai git review` ```bash scai git review ``` This will show you pull requests assigned to you for review: * Understand the diffs using a local model * Generate a structured pull request: * ✅ Title * ✅ Summary of changes * ✅ Explanation of why the changes matter * ✅ Optional changelog bullets SCAI supports an integrated review flow for GitHub pull requests. To get started: 1. **Set your working index directory (once per repo):** ```sh scai index set /path/to/repo ``` 2. **Authenticate with GitHub:** ```sh scai git review ``` This command will query you for the Personal Access Token and set it for you. You may also do this with the auth commands below ```sh scai auth set scai auth check ``` 3. **Fetch and review pull requests:** ```sh scai git review ``` Use `-a` to list all PRs that require a review: ```sh scai git review -a ``` #### Example Workflow ```sh $ scai git review -a 📦 Resolving GitHub repo info from indexDir: ./ 🔗 Git origin URL: git@github.com:org/repo.git ✅ Parsed: owner='org', repo='repo' 👤 Authenticated user: dev-user123 🔍 Fetching pull requests and diffs... ✅ Fetched 5 PR(s) with diffs. 📦 Open Pull Requests with review requested: | # | ID | TITLE | AUTHOR | STATUS | CREATED | REVIEWERS | REVIEWS | | - | ---- | ----------------------------- | ---------- | ------ | ---------- | ----------------------------- | ------------------- | | 1 | #120 | fix/session-timeout | dev-alice | Open | 2025-08-08 | code-analyzer\[bot], dev-bob | ✅ Approved | | 2 | #118 | feature/1482-support-wfs2 | dev-carol | Open | 2025-08-07 | code-analyzer\[bot], dev-dave | ✅ Approved | | 3 | #117 | refactor/win-server-support | dev-erin | Open | 2025-08-06 | dev-frank, dev-alice | ❌ Changes Requested | | 4 | #114 | bump/vue-i18n-9.14.5 | dependabot | Open | 2025-08-04 | code-analyzer\[bot] | ✅ Approved | | 5 | #113 | bugfix/null-navigator-check | dev-bob | Open | 2025-08-03 | dev-alice, dev-carol | ✅ Approved | 👉 Choose a PR to review [1-2]: 1 ✅ Model response received. 💡 AI-suggested review: Solid improvement — this patch improves session stability and handles async state more reliably. You might consider renaming `sessionManager` to better reflect its dual role in auth and persistence. --- 1) ✅ Approve 2) ❌ Reject 3) ✍️ Edit 4) Write your own review 5) 🚪 Cancel ``` ### 🔧 How to Use `scai git commit` Use AI to suggest a meaningful commit message based on your staged code: ```bash git add . scai git commit ``` You can also include a changelog entry along with the commit: ```bash scai git commit --changelog ``` This will: 1. Suggest a commit message based on your `git diff --cached` 2. Propose a changelog entry (if relevant) 3. Allow you to approve, regenerate, or skip the changelog 4. Automatically stage and commit the changes --- ### 📝 Generate a Standalone Changelog Entry If you want to generate a changelog entry without committing: ```bash scai gen changelog ``` This will: - Analyze the current `git diff` (staged or unstaged) - Propose a list of **user-facing changes** in clean markdown bullet points - Let you accept, regenerate, or skip the update - Append the entry to `CHANGELOG.md` and stage it if accepted ### 🛠️ Code Generation Commands (`gen` group) ```bash scai gen comm <file|folder...> scai gen summ <file> scai gen changelog scai gen tests <file> ``` * `comm`: Add comments to one or more files, or to all matching files in a folder (recursive). ```bash scai gen comm src/ utils/helpers.ts ``` This will add comments to all `.ts` and `.js` files under `src/` and to `utils/helpers.ts`. * `summ`: Summarize a file You can also pipe file content directly: ```bash cat src/utils/math.ts | scai gen summ ``` * `changelog`: Update or create `CHANGELOG.md` from Git diff * `tests`: Create Jest test stubs (ALPHA) --- ## ⚙️ Configuration scai stores settings in `~/.scai/config.json`. You can override or view them: * **Set model:** ```bash scai config set-model codellama:7b ``` * **Set language:** ```bash scai config set-lang ts ``` * **Show config:** To see the config for the active repo ```bash scai config show ``` To see the config for all repos ```bash scai config show --raw ``` --- ## Commands ### `index` The `index` command is used to manage and perform operations on the indexed files and repositories. It allows you to control which repository you're working with and have indexed. #### `scai index start` Index supported files in the configured index directory. ```bash scai index set <dir> ``` Or just this for cwd (current working dir) ```bash scai index set ``` Set and activate the index directory. ```bash scai index list ``` List all indexed repositories. ```bash scai index switch ``` Switch active repository (by key or indexDir). Run without input for an interactive list of repositories. #### `scai index delete` Delete a repository from the index (interactive). This removes the repository entry from the `config.json` file, but does **not** delete the repository folder on disk. ```bash scai index delete ``` --- ## 🛍️ Maintenance & Utilities # Database Commands Your CLI now supports a set of **database management commands** under the `db` namespace. These commands allow you to check the status of the database, reset it, or run migrations. --- ### 📋 Available Commands #### 🔍 Check Database ```bash scai db check ``` Runs the **dbcheck** script to verify the database status. * Useful for quickly checking if the database is healthy. * Prints detailed output directly in the console. --- #### ♻️ Reset Database ```bash scai db reset ``` Deletes and resets the SQLite database. * Will ask for confirmation before proceeding. * Respond with `y` or `Y` to confirm. * Any other key (including `n`, `N`, or just pressing **Enter**) will cancel the reset. --- #### 📦 Run Migrations ```bash scai db migrate ``` Executes all database migration scripts. Note the **Migrate** command is for **internal use only**. Do **not** run it unless explicitly instructed, as it may delete existing data or corrupt your local database. If you're upgrading from an earlier version, please run the following commands to avoid indexing issues: ```bash scai db reset scai index ``` --- ### ✅ Example Workflow 1. **Check** current database state: ```bash scai db check ``` 2. Confirm you're in the correct repo. ```bash scai index list ``` Use the switch command to switch if necessary. ```bash scai index switch ``` 2. If necessary, **reset** the database: ```bash scai db reset ``` → Confirm with `y` when prompted. --- ## 🔁 Background Daemon and Indexing ⚠️ ALPHA Notice These features are experimental and subject to change: * `find`, `ask` * `daemon`, `stop-daemon` * `gen tests` (test generation) > **Note:** Indexing very large repositories (millions of lines) may take **hours or days**. Please be patient, and only index huge codebases if you are ok with some extra processing taking place on your computer. The `scai index` command **automatically** starts a background daemon that continuously: * Scans your target directory * Summarizes new or changed files * Updates embeddings and the search index You won't gain much value from the index unless you scope it to one repository. --- > **Important:** You must `index` a **code repository** first or `find` and `ask` have no context to work with. 1. **Set index directory:** ```bash scai index set /path/to/repo ``` 2. **Index your repo (once):** ```bash scai index start ``` 3. The daemon is designed to **consume minimal resources** and run unobtrusively. You can control it with: ```bash scai daemon # Start or show daemon status scai stop-daemon # Stop the background indexer ``` 4. **Keyword search:** ```bash scai find YourClassName ``` 5. **Natural-language questions:** ### 🧠 Natural-language questions Ask questions about your codebase using `scai ask`. You can run it in two ways: 1. **Inline question** ```bash scai ask "How does the controller work?" ``` 2. **Interactive prompt** ```bash scai ask ``` **Press enter** , then type your question when prompted: ``` > How does the controller work? ``` ### 🚨 **OBS** 🚨 `find` and `ask` rely on that index—without it they will return no useful results. --- ### Backup only of `~/.scai`:** Creates a backup of the .scai folder in the user root dir. ```bash scai backup ``` Results in this: ~/.scai_backup_2025-08-12T06-58-00-227Z/ --- ## 🔐 License & Fair Use **scai is free to use** for individuals, teams, and commercial projects. You may: * ✅ Use internally or commercially * ✅ Fork and improve * ✅ Recommend to others You may **not**: * ❌ Resell as a product or service * ❌ Claim ownership of the tool ### 📄 License Free for personal and internal company use only. Commercial use (resale, SaaS, inclusion in paid tools) is prohibited. Contact me for commercial licensing. --- ## 🙌 Feedback Questions, ideas, or bugs? Ping [@ticcr](https://bsky.app/profile/ticcr.xyz) on Bluesky — I'd love to hear your thoughts! ---