{"id":29093123,"url":"https://github.com/ripan-roy/locopilot-ai","last_synced_at":"2026-04-28T13:34:38.293Z","repository":{"id":301433884,"uuid":"1009147752","full_name":"Ripan-Roy/locopilot-ai","owner":"Ripan-Roy","description":"Open-source, local-first agentic coding assistant. Automate, plan, and edit codebases using local LLMs, advanced memory, and interactive shell commands—all 100% private and extensible. 🚀","archived":false,"fork":false,"pushed_at":"2025-06-26T21:27:03.000Z","size":127,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-26T21:59:14.381Z","etag":null,"topics":["code-cli","llm","python","shell"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ripan-Roy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-26T16:48:23.000Z","updated_at":"2025-06-26T21:26:14.000Z","dependencies_parsed_at":"2025-06-26T21:59:21.810Z","dependency_job_id":"dd0610c8-23e2-440b-8e7d-67871e4cf4ec","html_url":"https://github.com/Ripan-Roy/locopilot-ai","commit_stats":null,"previous_names":["ripan-roy/locopilot-ai"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/Ripan-Roy/locopilot-ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ripan-Roy%2Flocopilot-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ripan-Roy%2Flocopilot-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ripan-Roy%2Flocopilot-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ripan-Roy%2Flocopilot-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ripan-Roy","download_url":"https://codeload.github.com/Ripan-Roy/locopilot-ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ripan-Roy%2Flocopilot-ai/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262396498,"owners_count":23304445,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-cli","llm","python","shell"],"created_at":"2025-06-28T08:06:03.310Z","updated_at":"2026-04-28T13:34:38.287Z","avatar_url":"https://github.com/Ripan-Roy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 Locopilot\n\n[![PyPI version](https://badge.fury.io/py/locopilot.svg)](https://badge.fury.io/py/locopilot)\n[![Python](https://img.shields.io/pypi/pyversions/locopilot.svg)](https://pypi.org/project/locopilot/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![GitHub stars](https://img.shields.io/github/stars/Ripan-Roy/locopilot-ai.svg?style=social\u0026label=Star)](https://github.com/Ripan-Roy/locopilot-ai)\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"assets/locopilot-demo.png\" alt=\"Locopilot Demo\" width=\"800\"/\u003e\n\u003c/div\u003e\n\nLocopilot is an open-source, local-first, agentic coding assistant built for developers. It leverages local LLMs (via Ollama), and advanced memory management using LangGraph, to automate, plan, and edit codebases—all inside an interactive shell.\n\n- **Private**: All code and prompts stay on your machine.\n- **Agentic**: Locopilot plans, edits, iterates, and manages your coding tasks.\n- **Interactive**: Drop into a shell, enter tasks or slash commands, and steer the agent in real time.\n- **Memory-Efficient**: Advanced memory compression via LangGraph for \"infinite\" context.\n- **Extensible**: Change models, modes, and add custom tools or plugins on the fly.\n\n## Table of Contents\n\n- [Features](#features)\n- [How It Works](#how-it-works)\n- [Architecture](#architecture)\n- [Getting Started](#getting-started)\n- [Usage: Interactive Shell \u0026 Commands](#usage-interactive-shell--commands)\n- [Project Structure](#project-structure)\n- [Extensibility \u0026 Roadmap](#extensibility--roadmap)\n- [Contributing](#contributing)\n- [License](#license)\n\n## ✨ Features\n\n- **Local LLM Backend**: Bring your own Ollama server and code with any open-source LLM.\n- **LangGraph Agent Workflow**: Plans, executes, edits, and compresses memory as a stateful, extensible graph.\n- **Interactive Shell/REPL**: After init, drop into a chat-like agent terminal—just type coding tasks or slash commands.\n- **Slash Command Support**: `/model`, `/change-mode`, `/concise`, `/clear`, `/new`, `/end`, `/help`, and more.\n- **Smart Memory Compression**: Automatically summarizes previous context using the LLM itself, supporting ultra-long sessions.\n- **Configurable**: Models, modes, and summarization thresholds are all runtime-editable.\n- **Pluggable Nodes**: Add file tools, planning modules, git ops, and vector-based retrieval easily.\n- **(Planned) Git Integration**: Auto-commit, rollback, and view code diffs per agent step.\n\n## ⚡️ How It Works\n\n### 1. Initialization\nRun `locopilot init` in your project root.\n- Locopilot checks Ollama, prompts for model, sets up `.locopilot/config.yaml`.\n- You're dropped into an interactive agent shell (REPL).\n\n### 2. Agentic Workflow (via LangGraph)\nEach user input is parsed:\n- **Slash command** (`/model`, etc.) → runs as a graph branch.\n- **Normal prompt** (task) → plans, edits, summarizes via a workflow graph:\n  ```\n  User Task → [Planning Node] → [File Edit Node] → [Memory Summarizer Node] → (Repeat)\n  ```\n- Memory is managed with a LangGraph memory node—summarizing, chunking, and compressing context as needed.\n\n### 3. Session Management\n- Change models, modes, or reset memory on the fly with slash commands.\n- All state (memory, model, mode) persists during the session.\n\n## 🏗️ Architecture\n\nKey components:\n\n- **CLI Layer**: Typer-based CLI, launches shell (REPL), parses slash commands.\n- **LangGraph Workflow**:\n  - **Nodes**: Planning, file edit, summarization, slash command handler, etc.\n  - **Edges**: Control session flow, branching between commands and prompts.\n- **LLM Backend**:\n  - **Ollama**: For running CodeLlama, DeepSeek, etc.\n- **Memory Layer**:\n  - LangChain/LangGraph memory objects (buffer, summary, vector, hybrid).\n  - Summarizes old context using the LLM to avoid hitting token/window limits.\n- **Config/Project Layer**:\n  - `.locopilot/config.yaml` stores model/backend/session preferences.\n\n### Stateful Graph Example:\n```\n               [User Input]\n                      |\n      +---------------+---------------+\n      |                               |\n [Slash Command]              [Prompt/Task]\n      |                               |\n[Command Handler]   [Plan]-\u003e[Edit]-\u003e[Summarize]-\u003e[Memory]\n      |                               |\n     END                             Loop\n```\n\n## 🛠 Getting Started\n\n### Requirements\n- Python 3.8+\n- Ollama running locally\n- pip\n\n### Install Locopilot\n\n**Option 1: Install from PyPI (Recommended)**\n```bash\npip install locopilot\n```\n\n**Option 2: Install from Source**\n```bash\ngit clone https://github.com/Ripan-Roy/locopilot-ai.git\ncd locopilot-backend\npip install -e .\n```\n\n### Start Your Local LLM\n\n**Ollama:**\n```bash\nollama serve\nollama pull codellama:latest\n```\n\n### Initialize and Enter the Agent Shell\n```bash\nlocopilot init\n```\n\nThis checks LLM backend, prompts for config, scans for project context, and launches the interactive shell.\n\n## 🖥️ Usage: Interactive Shell \u0026 Commands\n\nAfter init, Locopilot enters a shell where you can type prompts and commands:\n\n### Example Session\n```\n$ locopilot init\n[✓] Ollama running. Model: codellama:latest\n[✓] Project context initialized.\n\nLocopilot Shell (mode: do):\n\u003e Add OAuth login to my Django app\n[PLANNING] ...\n[EDITING] ...\n[MEMORY] ...\n\n\u003e /model\nCurrent model: codellama:latest\nEnter new model: deepseek-coder:latest\n[✓] Model switched to deepseek-coder:latest\n\n\u003e /change-mode\nCurrent mode: do\nAvailable modes: do, refactor, explain, chat\nEnter new mode: refactor\n[✓] Mode set to refactor.\n\n\u003e Refactor the payment logic for clarity\n...\n\n\u003e /concise\n[✓] Context summarized and compressed.\n\n\u003e /clear\n[✓] Session memory cleared.\n\n\u003e /new\n[✓] New session started.\n\n\u003e /end\n[✓] Session ended. Bye!\n```\n\n### Supported Slash Commands\n\n| Command | Purpose |\n|---------|---------|\n| `/model` | Change LLM model/backend for current session |\n| `/change-mode` | Switch between do, refactor, explain, chat modes |\n| `/clear` | Clear all current context/memory |\n| `/new` | Start a new session/project |\n| `/end` | End the agent shell and exit |\n| `/concise` | Force summarization/compression of current context |\n| `/help` | Show help and command list |\n\nAnything not starting with `/` is treated as a task in the current mode!\n\n## 🗂️ Project Structure\n\n```\nlocopilot-backend/\n├── locopilot/                  # Main package directory\n│   ├── __init__.py\n│   ├── core/                   # Core functionality\n│   │   ├── __init__.py\n│   │   ├── agent.py           # LangGraph workflow and nodes\n│   │   ├── memory.py          # Session/context memory management\n│   │   └── executor.py        # Plan execution engine\n│   ├── llm/                    # LLM backend handling\n│   │   ├── __init__.py\n│   │   ├── connection.py      # Ollama connection helpers\n│   │   └── backends/          # Backend-specific implementations\n│   ├── cli/                    # CLI components\n│   │   ├── __init__.py\n│   │   ├── app.py             # CLI entrypoint, shell/REPL logic\n│   │   └── commands/          # CLI command implementations\n│   └── utils/                  # Utility functions\n│       ├── __init__.py\n│       └── file_ops.py        # File operations, config helpers\n├── tests/                      # Test suite\n│   ├── conftest.py\n│   ├── test_agent.py\n│   ├── test_basic.py\n│   ├── test_connection.py\n│   └── test_plan_executor.py\n├── scripts/                    # Setup and utility scripts\n│   └── setup.sh\n├── docs/                       # Documentation\n├── assets/                     # Static assets\n│   └── locopilot-demo.png\n├── pyproject.toml             # Package configuration\n├── requirements.txt           # Dependencies\n├── README.md\n└── LICENSE\n```\n\n## 🧠 Memory Management (with LangGraph)\n\n- `ConversationBufferMemory` or `ConversationSummaryBufferMemory` is attached to the agent graph.\n- As session context grows, old steps are summarized using the LLM and replaced in memory.\n- This ensures Locopilot \"remembers\" key tasks, design decisions, and context for long sessions.\n- Slash command `/concise` lets you summarize on demand.\n\n## ⚡️ Extensibility \u0026 Roadmap\n\n- **Editor Plugins**: VSCode, Vim, JetBrains, etc.\n- **Project-Aware RAG**: Integrate vector DBs (Chroma, Qdrant) for smart codebase retrieval.\n- **(Planned) Git Integration**: Auto-commit, diff, and rollback per step.\n- **Save/Load Sessions**: `/save`, `/load`, `/history` commands.\n- **Custom Plugins/Nodes**: Add your own LangGraph nodes for tools or workflows.\n- **Web/GUI Frontends**: Same agent core, different interface.\n\n## 🤝 Contributing\n\n- Fork and PRs are welcome!\n- Open issues for bugs or feature requests.\n- For major features (graph nodes, memory backends), see CONTRIBUTING.md (coming soon).\n\n## 📝 License\n\nMIT License. Use, fork, and extend as you wish!\n\n## 💡 Inspiration\n\nLocopilot is inspired by Copilot, Claude Code, Dev-GPT, OpenDevin, and the emerging open-source agentic ecosystem—aiming to empower developers with private, supercharged, customizable AI tools.\n\n## 🚦 Quickstart\n\n```bash\n# Install from PyPI\npip install locopilot\n\n# Initialize in your project\nlocopilot init\n\n# ... then just type your coding tasks and manage the session with slash commands!\n```\n\n**Links:**\n- [PyPI Package](https://pypi.org/project/locopilot/)\n- [GitHub Repository](https://github.com/Ripan-Roy/locopilot-ai)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fripan-roy%2Flocopilot-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fripan-roy%2Flocopilot-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fripan-roy%2Flocopilot-ai/lists"}