<div align="center">

<img src="https://lab.getnexora.cloud/og-banner.png" alt="Nexora Code Banner" width="100%">

# Nexora Code

**Professional multi-model AI coding agent & terminal.**  
Built for engineers who don't want to leave the terminal.

[![npm version](https://img.shields.io/npm/v/nexora-code?color=6C63FF&label=nexora-code&style=flat-square)](https://www.npmjs.com/package/nexora-code)
[![npm downloads](https://img.shields.io/npm/dm/nexora-code?color=00D2FF&style=flat-square)](https://www.npmjs.com/package/nexora-code)
[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square)](https://nodejs.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-yellow?style=flat-square)](./LICENSE)
[![Docs](https://img.shields.io/badge/docs-lab.getnexora.cloud-6C63FF?style=flat-square)](https://lab.getnexora.cloud/docs)

[**📖 Documentation**](https://lab.getnexora.cloud/docs) · [**🐛 Report a Bug**](https://github.com/enochboadu/nexora-code/issues) · [**💡 Request a Feature**](https://github.com/enochboadu/nexora-code/issues)

</div>

---

## What is Nexora Code?

Nexora Code is a **fully open-source, terminal-native AI coding agent** that brings Gemini-style conversational intelligence directly into your workflow. It is built on a BYOK (Bring Your Own Key) model — you connect your own API keys from providers like Gemini, Anthropic, OpenAI, OpenRouter, and Groq, and Nexora Code handles everything else.

Unlike browser-based AI tools, Nexora Code lives entirely in your terminal:

- **Multi-action agent** — reads, writes, refactors and fixes files autonomously
- **Conversation memory** — sessions persist across restarts
- **Smart auto-routing** — picks the right model for code vs. general tasks
- **50+ built-in tools** — file ops, Git integration, AST mapping, semantic search, web fetch, test runner, and more
- **Multi-provider BYOK** — swap models on the fly without reconfiguring
- **Session history** — browse and resume past conversations with `/chats`
- **Background tasks** — run long agent jobs non-interactively via `--headless`
- **OS Keychain integration** — API keys stored securely in your native keychain, never in plaintext

---

### Install via npm

The fastest way to get started. Requires **Node.js v20+**:

```bash
npm install -g nexora-code
```

Or run directly without installing:

```bash
npx nexora-code
```

Nexora Code will guide you through connecting your first API key on first launch.

---

## Quick Start

```bash
# Start interactive chat
nexora

# Ask the agent to write or modify code
nexora write "build a REST API in Express with user auth"

# Fix a file
nexora fix src/components/Button.tsx

# Index your project into memory
nexora scan

# Run a one-shot prompt (CI/scripting)
echo "Summarise this file" | nexora --headless
```

---

## Supported Providers

Nexora Code is model-agnostic. Connect any combination of these providers:

| Provider       | Models                                      |
|----------------|---------------------------------------------|
| **Gemini**     | Gemini 2.0 Flash, Gemini 1.5 Pro, and more |
| **Anthropic**  | Claude 3.5 Sonnet, Claude 3 Haiku, and more|
| **OpenAI**     | GPT-4o, GPT-4o Mini, o1, and more          |
| **OpenRouter** | 200+ models via a single key               |
| **Groq**       | Llama 3.1, Mixtral, Gemma (ultra-fast)     |

Manage keys at any time:
```bash
nexora auth login gemini
nexora auth list
nexora auth remove openai
```

---

## Commands

### CLI (one-off)

| Command                    | Description                                          |
|----------------------------|------------------------------------------------------|
| `nexora`                   | Start interactive Chat mode                          |
| `nexora scan`              | Index current project folder into semantic memory    |
| `nexora write <desc>`      | Generate files from a description (Agent mode)       |
| `nexora fix <file>`        | Analyse and fix a file autonomously (Agent mode)     |
| `nexora auth login <p>`    | Add or rotate an API key for a provider              |
| `nexora auth list`         | List all configured providers                        |
| `nexora auth remove <p>`   | Remove a provider's API key                          |
| `nexora doctor`            | System health: keys, DB, cache, bootstrap state      |
| `nexora stats`             | Token usage, cache hit rate, cost estimates          |
| `nexora debug`             | Internal paths, config state, runtime diagnostics    |
| `nexora task create <job>` | Spawn a background agent task                        |
| `nexora task list`         | Show running background tasks                        |
| `nexora reset`             | Factory reset: wipe config, memory, and API keys     |
| `nexora uninstall`         | Clean local data and guide through full removal      |
| `nexora --headless`        | Pipe a prompt via stdin for scripting / CI use       |
| `nexora --version`         | Show version                                         |
| `nexora --help`            | Full command reference                               |

### Inside the REPL

| Command              | Description                                    |
|----------------------|------------------------------------------------|
| `/new`               | Start a blank new conversation                 |
| `/chats`             | Browse and resume past conversations           |
| `/chat models`       | List & select a model for Chat mode            |
| `/agent models`      | View & change Agent models                     |
| `/auto`              | Toggle smart auto-model routing                |
| `/mode agent`        | Switch to Agent mode (file read/write)         |
| `/mode chat`         | Return to Chat mode                            |
| `/mode auto`         | Agent auto-approves all trusted writes         |
| `/mode plan`         | Agent previews full plan before executing      |
| `/scan`              | Index current project into semantic memory     |
| `/write <desc>`      | Generate or create files from a description    |
| `/fix <file>`        | Analyse a file for bugs and patch it           |
| `/resume`            | Resume the last interrupted agent session      |
| `/history`           | Recent agent sessions and their status         |
| `/setup`             | Re-run the API key setup wizard                |
| `/auth`              | Manage API keys (login, list, remove)          |
| `/doctor`            | Show system health report                      |
| `/stats`             | Token usage and cost stats                     |
| `/debug`             | Internal paths and config state                |
| `/task create <job>` | Start a background task                        |
| `/task list`         | Show all running background tasks              |
| `/task watch`        | Stream output from a running task              |
| `/task result`       | View the output of a completed task            |
| `/task cancel`       | Cancel a running background task               |
| `/clear`             | Redraw the full UI                             |
| `/help`              | Show command reference                         |
| `exit`               | Quit Nexora Code                                |

---

## Uninstall

### Using the CLI (Recommended)

```bash
nexora uninstall
```

This removes local configuration, sessions, and API keys, then prints the final npm command to complete removal.

```bash
npm uninstall -g nexora-code
```

**Modes:**

| Mode                        | What it removes                                    |
|-----------------------------|----------------------------------------------------|
| `nexora uninstall`          | `~/.nexora`, keychain tokens                       |
| `nexora uninstall --soft`   | Config & keys only, preserves logs & cache         |
| `nexora uninstall --deep`   | Complete wipe of all local Nexora data             |
| `nexora reset`              | Wipes config & memory, keeps the binary installed  |

---

## Project Structure

```
nexora-code/
├── src/
│   ├── index.ts                ← Entry point & CLI router
│   ├── types.ts                ← Global type definitions
│   ├── agent/                  ← Agent engine, tools, session, safety
│   │   ├── engine.ts           ← Multi-action agent loop
│   │   ├── tools.ts            ← 50+ built-in agent tools
│   │   ├── autonomy-engine.ts  ← Fully autonomous task execution
│   │   ├── safety-engine.ts    ← Rollback, sandboxing, approval gates
│   │   ├── semantic-rag.ts     ← Retrieval-augmented generation
│   │   ├── vector-search.ts    ← Semantic project indexing
│   │   ├── procedural-memory.ts← Memory for long-term task contexts
│   │   ├── git-tools.ts        ← Native Git integration tools
│   │   ├── scaffold-tools.ts   ← Boilerplate and template generation
│   │   ├── deploy-tools.ts     ← Deployment automation tools
│   │   ├── test-tools.ts       ← Automated testing and validation
│   │   └── subagents.ts        ← Swarm subagent orchestration
│   ├── commands/               ← CLI subcommands
│   │   ├── chat.ts             ← REPL loop, memory, streaming
│   │   ├── auth.ts             ← API key management
│   │   ├── init.ts             ← Project initialization wizard
│   │   ├── tasks.ts            ← Background task manager
│   │   ├── doctor.ts           ← Diagnostics & health checks
│   │   └── uninstall.ts        ← Uninstallation wizard
│   ├── config/                 ← Configuration files
│   │   ├── agent-config.ts     ← Agent behavior settings
│   │   └── chat-config.ts      ← Chat UI and model configurations
│   ├── core/                   ← Infrastructure layer
│   │   ├── provider-registry.ts← Multi-provider BYOK routing
│   │   ├── context-manager.ts  ← Token budget & context windowing
│   │   ├── circuit-breaker.ts  ← Provider failover & retries
│   │   ├── ast-mapper.ts       ← Abstract Syntax Tree analysis
│   │   ├── telemetry.ts        ← Performance and metric tracking
│   │   └── sandbox.ts          ← Isolated execution environment
│   └── utils/                  ← Shared utilities
│       ├── bootstrap.ts        ← Runtime environment validation
│       ├── keychain.ts         ← OS keychain integration
│       ├── mcp-client.ts       ← Model Context Protocol client
│       ├── multi-project.ts    ← Multi-workspace management
│       ├── learning-system.ts  ← Adaptive learning from feedback
│       ├── router.ts           ← Smart auto-model routing logic
│       ├── db.ts               ← SQLite database connection
│       └── ui.ts               ← Terminal UI chrome & animations
├── packaging/                  ← Platform install/uninstall scripts
├── .github/workflows/          ← CI/CD pipelines
└── package.json
```

---

## Architecture Highlights

- **ESM-native TypeScript** — fully typed, no legacy JavaScript baggage
- **Single bundled binary** — esbuild bundles everything into `dist/bundle.cjs` so installation is a single npm command
- **OS Keychain security** — API keys are stored in macOS Keychain, Windows Credential Manager, or Linux Secret Service via `keytar`. Never written to disk in plaintext.
- **SQLite + Vector Search** — `better-sqlite3` + `sqlite-vss` powers semantic code search, session history, and caching
- **Provider Circuit Breaker** — automatic failover to backup providers if a primary provider times out or errors
- **Safety Gates** — all destructive agent actions (file writes, deletes, shell commands) require explicit confirmation unless running in `--auto` mode

---

## Contributing

Contributions are very welcome! Nexora Code is MIT-licensed and community-first.

**Good first issues include:**
- Adding new agent tools
- Improving provider support (new models, APIs)
- Enhancing the terminal UI
- Writing tests and docs

**To get started:**
```bash
git clone https://github.com/enochboadu/nexora-code
cd nexora-code
npm install
npm start          # Run in development mode
```

For larger changes, please open an issue first to discuss your idea. We review PRs actively.

---

## Roadmap

- [ ] Cloud session sync across machines
- [ ] MCP (Model Context Protocol) full integration
- [ ] Multi-agent orchestration (spawn sub-agents for parallel tasks)
- [ ] Plugin marketplace for community tools
- [ ] Nexora Cloud — hosted model gateway with no BYOK required
- [ ] VS Code extension with shared context

Follow development at [lab.getnexora.cloud](https://lab.getnexora.cloud) and star the repo to stay updated.

---

## Data Storage

All Nexora Code data is stored under `~/.nexora/` on all platforms:

| File / Directory       | Contents                              |
|------------------------|---------------------------------------|
| `config.json`          | Preferences, model selection          |
| `state.json`           | Bootstrap and setup state             |
| `nexora.db`            | Session history, semantic index       |
| `sessions/`            | Conversation session archives         |
| `logs/`                | Debug logs                            |
| `cache/`               | Response cache                        |

API keys are **not** stored in `~/.nexora`. They live exclusively in your OS keychain.

---

## License

MIT © [Nexora Inc.](https://getnexora.cloud) — Founded 2026 by Enoch Boadu

> Nexora Code is the open-source core of the Nexora developer platform. The goal is to make professional AI-assisted development accessible to every engineer on every team — regardless of which AI provider they prefer or how much they want to spend.
