somaliagent-cli

A terminal-based AI coding agent focused on UI/UX and developer experience. It runs locally in your terminal and helps you with file management, code generation, code editing, project analysis, refactoring, and task automation.

Features

• Terminal UI — Clean, minimal, modern terminal interface with clear prompts and mode indicators
• Build Mode — Apply file changes directly (create, read, update, delete files)
• Plan Mode — Get implementation plans without modifying any files
• Dual AI Provider — Supports both Gemini and OpenRouter
• Keyboard Shortcuts — Tab to switch modes, Esc to clear, Ctrl+C to exit
• Project Context — Automatically reads your project structure for informed responses
• Safe File Operations — Backups before updates/deletes, path validation, change summaries
• NPM Global Install — Run from anywhere with somaliagent

Installation

Global NPM Install

npm install -g somaliagent-cli

Then run:

somaliagent

Or:

somaliagent-cli

Local Development

git clone https://github.com/somaliagent/somaliagent-cli.git
cd somaliagent-cli
npm install
npm link
somaliagent

Or without linking:

node bin/somaliagent.js

Setup

1. Create a .env file

Copy the example environment file:

cp .env.example .env

2. Add your API keys

Edit .env and add at least one API key:

GEMINI_API_KEY=your_gemini_key_here
OPENROUTER_API_KEY=your_openrouter_key_here
OPENROUTER_MODEL=google/gemini-2.5-flash-lite
DEFAULT_PROVIDER=gemini

Gemini API Key

1. Go to Google AI Studio
2. Click "Get API Key"
3. Create a new API key
4. Copy it to GEMINI_API_KEY in .env
5. DEFAULT_PROVIDER=gemini is set by default

OpenRouter API Key

1. Go to OpenRouter
2. Sign in and create a new API key
3. Copy it to OPENROUTER_API_KEY in .env
4. Set DEFAULT_PROVIDER=openrouter

Usage

Build Mode

In Build mode, the agent can directly create, read, update, and delete files in your project.

◆ BUILD > Create a React button component with hover effects

The agent will:

• Generate the component code
• Create the file
• Show a summary of changes

Plan Mode

In Plan mode, the agent only explains what should be done without modifying any files.

◇ PLAN > I need to add authentication to my app

The agent will respond with:

• What needs to be done
• Which files are affected
• Step-by-step implementation plan
• Risks and considerations

Every Plan mode response ends with:

No files were modified. Switch to Build mode to apply this plan.

Keyboard Shortcuts

| Key | Action | |-----|--------| | Tab | Switch between Build and Plan mode | | Esc | Clear current input | | Enter | Submit prompt | | Ctrl + C | Exit cleanly | | exit | Exit cleanly |

Project Structure

somaliagent-cli/
├── bin/
│   └── somaliagent.js         # CLI entry point
├── src/
│   ├── cli.js                  # Main CLI orchestration
│   ├── agent.js                # Request processing pipeline
│   ├── ai/
│   │   ├── index.js            # AI provider router
│   │   ├── prompts.js          # System prompts for Build/Plan modes
│   │   └── providers/
│   │       ├── gemini.js       # Gemini API provider
│   │       └── openrouter.js   # OpenRouter API provider
│   ├── core/
│   │   ├── context.js          # Project context reader
│   │   ├── executor.js         # Safe file CRUD operations
│   │   └── planner.js          # Action parser from AI responses
│   ├── ui/
│   │   ├── input.js            # Terminal input handling with raw mode
│   │   └── renderer.js         # Terminal UI rendering
│   └── utils/
│       ├── colors.js           # Chalk color theme
│       ├── logger.js           # Logging helpers
│       └── paths.js            # Path validation and utilities
├── .env.example                # Example environment file
├── .gitignore
├── package.json
└── README.md

Examples

Code Generation

◆ BUILD > Generate a responsive navbar component with Tailwind CSS

Refactoring

◆ BUILD > Refactor the handleSubmit function to use async/await

Planning

◇ PLAN > How should I structure my Express API routes?

File Operations

◆ BUILD > Create a utils/helpers.js file with debounce and throttle functions

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -m 'Add my feature')
4. Push to the branch (git push origin feature/my-feature)
5. Open a Pull Request

Please follow the existing code style and keep the codebase clean and minimal.

Publishing to NPM

npm login
npm publish

To install the published package:

npm install -g somaliagent-cli

License

MIT