GitHub - asgarovf/locusai: 🤖 Local-first workspace for agentic engineering. Unified tasks, docs, and secure CI for AI agents.

Locus is an AI-native project management platform for engineering teams.

Plan sprints, manage tasks, and coordinate documentation in the cloud—while AI agents run securely on your machine to build, test, and document your software.

Read the full documentation to learn more.

Locus is the platform that manages your projects. Your actual product code lives in separate repositories.

Key Features

• AI-Native Planning — Plan sprints, define tasks, and write documentation designed for AI agents. Use AI-powered sprint planning with a multi-agent meeting (Tech Lead, Architect, Sprint Organizer) to break down goals into structured, prioritized tasks.
• Secure Local Execution — Agents run on your machine (or your server). Source code never leaves your infrastructure—only task metadata is synced to the cloud.
• Multiple AI Providers — Choose between Claude (Anthropic) and Codex (OpenAI) as your agent backend. Switch providers per-command or set a default.
• Team Coordination — Cloud-based dashboard for visibility, collaboration, sprint boards, document editing, and task management.
• Cognitive Context — Agents receive rich context including project instructions (.locus/LOCUS.md), semantic codebase index, workspace documents, sprint progress, and task details.
• AI Code Review — Review pull requests or local changes with AI-powered analysis directly from the CLI.
• Skills System — Extend agent capabilities with markdown instruction files for specialized domain knowledge.
• Telegram Bot — Control agents, plan sprints, approve plans, and monitor execution remotely from your phone.
• Self-Hosting — Deploy Locus on your own server for 24/7 agent availability with remote Telegram control.
• AI Discussions — Start interactive AI discussions with full project context. Extracts structured insights (decisions, requirements, ideas, concerns) as the conversation progresses.
• VSCode Extension — Chat with agents, explain code selections, and run exec tasks directly from your editor.

Quick Start

1. Install locus as global package

npm install -g @locusai/cli

2. Initialize a new project

3. Setup your configuration

4. Run the agent

Start agents to pick up and execute tasks from your active sprint:

Use a different provider:

locus run --provider codex

CLI Commands

How It Works

Architecture

locus-dev/                       ← The platform (Open Source)
├── apps/
│   ├── api/                     ← Cloud API & Engine (NestJS)
│   ├── web/                     ← Cloud Dashboard (Next.js)
│   └── www/                     ← Landing Page (Next.js)
└── packages/
    ├── cli/                     ← Local Agent Runtime & CLI
    ├── sdk/                     ← Core Logic & API Client
    ├── shared/                  ← Shared Types & Schemas
    ├── vscode/                  ← VSCode Extension
    └── telegram/                ← Telegram Bot for Remote Control

The Workflow

1. Plan — Define tasks manually in the dashboard, or use locus plan "your goal" to have AI agents break down your objective into a structured sprint.
2. Dispatch — Start agents with locus run. The API dispatches tasks with server-side locking to prevent conflicts.
3. Execute — Each agent claims a task, creates an isolated git branch, builds rich context, and executes using your chosen AI provider.
4. Review — Agents commit changes, push branches, and create pull requests. Review with locus review or in GitHub. Reject tasks with feedback to send them back for rework.

Project Structure

After running locus init, your project will have:

your-project/
├── .locus/
│   ├── config.json              # Project metadata
│   ├── settings.json            # API key & provider (gitignored)
│   ├── LOCUS.md                 # Agent instructions
│   ├── LEARNINGS.md             # Continuous learning log
│   ├── codebase-index.json      # Semantic index
│   ├── documents/               # Synced workspace documents
│   ├── artifacts/               # Generated files
│   ├── sessions/                # Exec session history
│   ├── reviews/                 # Code review reports
│   └── plans/                   # Sprint plans

Telegram Bot

Control your agents remotely with the built-in Telegram bot:

• /plan — Start AI sprint planning
• /approve / /reject — Approve or reject generated plans
• /run — Start agents remotely
• /exec — Execute a prompt with repo context
• /tasks — List active tasks
• /stop — Stop running processes
• /git — Run whitelisted git commands
• /dev — Run lint, typecheck, build, or test

Set up with locus telegram and connect your Telegram chat.

Self-Hosting

Deploy Locus on your own server for 24/7 agent availability:

curl -fsSL https://locusai.dev/install.sh | bash

The installer sets up Node.js, Bun, GitHub CLI, your chosen AI provider CLI, and configures system services for automatic startup. Supports Linux (systemd), macOS (LaunchAgent), and Windows (Scheduled Tasks).

See the self-hosting guide for full details.

Development

For detailed instructions on how to set up the development environment, run tests, and contribute code, please see CONTRIBUTING.md.

# Quick check
bun run lint && bun run typecheck

License

MIT