npm package: @inventeer.tech/apex
Description: AI-powered software delivery agent
Latest version: 0.2.49

# @inventeer.tech/apex

**AI-powered software delivery agent. From task description to open pull request — across multiple repos.**

[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey?style=flat)]()
[![License MIT](https://img.shields.io/badge/license-MIT-blue?style=flat)](https://github.com/Inventeer/apex/blob/main/LICENSE)
[![npm](https://img.shields.io/npm/v/@inventeer.tech/apex?style=flat)](https://www.npmjs.com/package/@inventeer.tech/apex)

---

## What is APEX?

APEX is a terminal CLI that takes a developer from a Linear ticket to open pull requests across all their repositories — with full codebase awareness, persistent memory, and zero configuration files left in repos.

You describe the task, approve the plan, and watch the changes land in real time across every repository in your stack.

**What runs on your machine:** the `apex` binary, a native AI runtime engine, and your git repos.  
**What lives in the cloud:** codebase semantic search (RAG), episodic session memory, LLM proxy, org config.  
**What never happens:** files created in your repos.

---

## Install

```bash
# npm (cross-platform)
npm install -g @inventeer.tech/apex

# macOS — Homebrew
brew install Inventeer/tap/apex
```

The binary is self-contained — no Go, Docker, or external runtime required.

```bash
apex version   # verify install
apex doctor    # run pre-flight checks
```

---

## Why APEX is Different

| | Terminal AI assistant | Autonomous cloud agent | **APEX** |
|---|---|---|---|
| **Scope** | One file at a time | One task, one repo | One task, **all repos** |
| **Execution** | Local, inline edits | Remote sandbox — you wait | Local — you watch changes live |
| **Plan approval** | No | No | **Yes — nothing runs without your sign-off** |
| **Memory between sessions** | None | Limited | **Episodic memory — resumes in <500 tokens** |
| **Codebase context** | Open files only | Repo snapshot | **Full RAG across all repos, always fresh** |
| **Org knowledge** | None | None | **ADRs, runbooks, specs — permanently searchable** |
| **Architectural decisions** | None | None | **Logged automatically, queryable** |
| **Delivery workflow** | Chat | Autonomous | **Phased: investigate → plan → implement → validate → ship** |
| **Quality gate** | Manual | Basic CI | **Pre-PR: tests + lint + type check + auto-fix** |
| **Token visibility** | None | None | **Per-model usage tracking** |

### An invisible senior engineer on every task

Every time you run a command in APEX, a curated framework of specialized agents, skills, and guardrails activates silently in the background — loaded from the cloud at startup, invisible to you, updating without any action on your part.

**8 specialized agents** swap in automatically depending on what you're doing:

- `/eng.start` activates the delivery agent — investigates, recalls past sessions, maps cross-repo dependencies
- `/eng.pre-pr` activates the code reviewer + QA test planner in parallel
- `/eng.debug` activates the bug hunter — root-cause analysis, not guessing
- `/qa-gate` activates the quality champion with numeric scoring

**30+ operational skills** activate on demand, invisibly:

- Detected sequential DB writes? The `eng-database` skill activates — transaction boundaries, rollback scenarios, isolation levels
- Found `.graphql` files in scope? The `eng-graphql` skill activates — schema validation, codegen, type contracts
- Pre-PR check? `qa-static-analysis`, `qa-security-scan`, `qa-test-plan`, and `eng-confidence` run in sequence
- Opening PRs? `eng-pr` and `eng-github` ensure branch naming, commit conventions, and cross-repo dependency notes

**Phase guardrails enforced by rules, not discipline:**

- `/eng.start` — no code written, analysis only
- `/eng.plan` — no code, no commits, plan only
- `/eng.work` — no commits until `/eng.pr`
- Acceptance criteria must exist before investigation proceeds
- Breaking changes require documented consumer impact

None of this requires configuration. It's part of every session, for every developer in your organization.

---

## The Workspace Concept

> This is the most important thing to understand about APEX.

A **workspace** is a named group of repositories that APEX treats as a single unit. When you start a task, APEX reads, understands, and writes code across **all repos in the workspace simultaneously** — like a senior engineer who has the full stack loaded in their head.

```
workspace: payment-platform
  ├── backend/          (Node.js API)
  ├── frontend/         (React app)
  └── shared-types/     (TypeScript contracts)
```

When APEX works on `ENG-123: add refund endpoint`, it:
- Reads the backend schema, frontend payment hooks, and shared type definitions
- Generates a plan that touches all three repos
- Writes changes across all repos in one session
- Opens one PR per repo, with cross-repo dependency notes in each body

**You register each repo once**, then forget about it:

```bash
cd ~/repos/backend      && apex init
cd ~/repos/frontend     && apex init
cd ~/repos/shared-types && apex init
```

APEX detects the git remote and technology stack automatically. All three repos are now in the same workspace.

---

## Setup (once per machine)

### 1 — Install and authenticate

```bash
npm install -g @inventeer.tech/apex
apex login
```

`apex login` opens the GitHub Device Flow in your browser. After approval, your organization's AI configuration — models, credentials, and behavior — is loaded automatically from the cloud.

### 2 — Connect Linear

```bash
apex auth linear
```

This opens the Linear OAuth flow. Once connected, APEX fetches full ticket details, acceptance criteria, and linked issues every time you start a task with a Linear ID.

### 3 — Register your repos

Run from inside each repository you want APEX to work with:

```bash
cd ~/repos/backend      && apex init
cd ~/repos/frontend     && apex init
```

APEX auto-detects the git remote and groups repos into a workspace.

### 4 — Index the codebase

```bash
apex index
```

Reads all source files, chunks them into overlapping segments, generates semantic embeddings, and stores them for search. Run once after registration, and again after large changes.

> The TUI shows an amber warning when the RAG index is more than 24 hours old.

### 5 — Launch

```bash
apex
```

APEX opens the workspace selector and the 3-panel TUI. From here, everything happens through slash commands.

```
╔═══════════════════════════════════════════════════════════════════════════╗
║  APEX  ▸  payment-platform                                   v0.2.32     ║
╠══════════════════╦════════════════════════════════╦════════════════════════╣
║  Workspace       ║                                ║  Live Diff             ║
║  ──────────────  ║   APEX                         ║  ────────────────────  ║
║  • backend       ║   Workspace ready:             ║  backend/              ║
║  • frontend      ║   › 2 repos indexed            ║   src/payments/        ║
║  • shared-types  ║   › 4,139 files in RAG         ║    client.ts  +12 -3   ║
║                  ║   › Episodic memory: 7 sessions║                        ║
║  Sessions        ║                                ║  frontend/             ║
║  ─────────────── ║   Type /init-apex to begin     ║   src/checkout/        ║
║  1 paused        ║   or /warm-up to load context  ║    Payment.tsx  +8 -1  ║
╠══════════════════╩════════════════════════════════╩════════════════════════╣
║  ›  _                                                                     ║
╚═══════════════════════════════════════════════════════════════════════════╝
```

---

## The Delivery Workflow

Every engineering task follows this sequence inside the TUI.

---

### `/init-apex`  ·  Initialize (first use)

```
/init-apex
```

Run once when starting in a new workspace. APEX loads your organization's configuration, reads environment files across repos, and bootstraps the session context.

---

### `/warm-up`  ·  Load context (start of each day)

```
/warm-up
```

APEX reads git status across all repos, loads recent architectural decisions, recalls past sessions, and builds a fresh summary of where things stand. Run this each morning or at the start of a new session. Takes ~30 seconds.

---

### `/eng.start ENG-XX`  ·  Investigate

```
/eng.start ENG-123
```

APEX fetches the Linear ticket (description, acceptance criteria, linked issues), recalls relevant past sessions from episodic memory, and searches the codebase via semantic RAG. It produces a full cross-repo investigation report with a clear problem statement and scope.

---

### `/eng.plan`  ·  Build the execution plan

```
/eng.plan
```

Based on the investigation, APEX generates a phased cross-repo implementation plan — broken into atomic tasks, one per file or concern, across all affected repos. Review the plan carefully.

```
  [ A ] Approve   [ E ] Edit   [ C ] Cancel
```

Nothing is written until you approve.

---

### `/eng.work`  ·  Execute

```
/eng.work
```

APEX executes the approved plan. The **Live Diff panel** updates in real time as files change across every repo. The AI runs tests as it goes, self-corrects on failures (up to 3 attempts per task), and records every architectural decision it makes.

You can watch, step away, or answer questions if prompted.

---

### `/eng.pre-pr`  ·  Quality gate

```
/eng.pre-pr
```

Before opening PRs, APEX runs a full validation pass across all repos:
- Unit and integration tests
- Type checking
- Lint
- Cross-repo dependency consistency

Failures are auto-fixed. You receive a scored quality report with a pass/fail verdict.

---

### `/eng.pr`  ·  Ship

```
/eng.pr
```

APEX opens **one PR per repo**, each with:
- A description derived from the ticket
- A summary of what changed and why
- Cross-repo dependency notes (e.g. `shared-types#42` must merge first)
- Linear ticket status updated automatically

---

## Session Memory in Practice

```
Monday 5pm:   you close the terminal, task 70% done
Tuesday 9am:  apex session resume <id>
              → AI picks up exactly where it stopped, no re-explaining needed
```

---

## Slash Commands Reference

| Command | Phase | What it does |
|---|---|---|
| `/init-apex` | Setup | Initialize workspace config and load org context |
| `/warm-up` | Daily | Load git status, decisions, and workspace summary |
| `/eng.start ENG-XX` | Investigate | Fetch ticket, search codebase, produce investigation |
| `/eng.plan` | Plan | Generate phased cross-repo implementation plan |
| `/eng.work` | Implement | Execute approved plan across all repos |
| `/eng.pre-pr` | Validate | Tests, lint, type check, auto-fix failures |
| `/eng.pr` | Ship | Open one PR per repo, update Linear ticket |
| `/eng.debug` | Debug | Root-cause analysis and incident investigation |
| `/eng.review` | Review | Review current diff and staged changes |
| `/eng.docs` | Document | Update technical docs and READMEs |
| `/qa-gate` | QA | Full quality gate with numeric scoring |

---

## CLI Reference

```bash
apex                           # Open workspace selector and launch
apex login                     # Authenticate with GitHub
apex logout                    # Remove stored credentials
apex auth linear               # Connect Linear via OAuth
apex init                      # Register current repo in a workspace
apex index                     # Index workspace repos for semantic search
apex index --repo backend      # Index a specific repo only
apex index --full              # Force full re-index (clears previous)
apex doctor                    # Run pre-flight health checks
apex session list              # List paused sessions
apex session resume <id>       # Resume a paused session
apex workspace list            # List all workspaces
apex workspace edit <name>     # Add or remove repos from a workspace
apex knowledge add <path>      # Upload docs/ADRs to org knowledge base
apex knowledge search <query>  # Semantic search over knowledge base
apex usage                     # Show token consumption by model/provider
apex decisions                 # Show saved architectural decisions
apex logs                      # Tail the latest AI engine log
apex version                   # Print version
```

---

## Common Questions

**Q: Does APEX create any files in my repos?**  
Two files, both intentional. `/init-apex` creates `ENV.md` — a workspace environment reference that should go in `.gitignore`. It also creates `AGENTS.md` — an AI context file that should be committed to the repo so the AI understands the codebase conventions. Beyond these, no configuration, state, or lock files are ever created in your repos.

**Q: Do I need to re-explain my codebase every session?**  
No. APEX indexes your code semantically and stores structured session summaries. Both are injected automatically into every LLM call. After months of work, APEX still knows why things were built the way they were.

**Q: What if a task spans 4 repos?**  
Register all 4 with `apex init`. APEX operates across all of them in every session. The plan, code changes, and PRs span all repos automatically.

**Q: Can I start a task without a Linear ticket?**  
Yes. Describe the task in plain English directly in the TUI:
```
› /eng.start add rate limiting to the payments API, 100 req/min per user
```

**Q: How do I pause mid-task and resume tomorrow?**  
Close the terminal (Ctrl+C). APEX automatically generates a structured session summary. Tomorrow, run `apex session resume <id>` and the AI picks up exactly where it left off.

**Q: What happens if a test fails during `/eng.work`?**  
APEX auto-corrects up to 3 times per failure, trying different strategies. If it can't resolve it, it surfaces a recovery report explaining what it tried and what's blocked.

---

## Links

- [GitHub](https://github.com/Inventeer/apex)
- [Documentation](https://github.com/Inventeer/apex/tree/main/docs)
- [Get Started Guide](https://github.com/Inventeer/apex/blob/main/docs/get-started.md)
- [Releases](https://github.com/Inventeer/apex-releases/releases)
- [Issues & Feedback](https://github.com/Inventeer/apex/issues)

---

## License

MIT © [Inventeer](https://github.com/Inventeer)