A local-first AI coding workspace that connects an Agent loop, safe tools, code RAG, model providers, and a developer-friendly UI around real repositories.

AICodePilot is not a chatbot wrapper. It is an engineering-oriented AI Agent workspace for understanding, searching, debugging, and improving local codebases. The backend combines FastAPI, an Agent executor, OpenAI-compatible tool calling, safe file/search/log/patch tools, retrieval-augmented generation (RAG), SQLite conversation history, and provider abstraction. The frontend provides a focused three-column workspace for model selection, project indexing, chat, Agent trace, and code evidence.

中文用户快速提示: AICodePilot 是一个本地优先的 AI 编程工作台。后端真实支持 OpenAI 和 DeepSeek，可以索引本地项目、调用安全工具、展示 Agent 执行轨迹和代码证据。最快启动方式见 Quick Start，常见中文问题见 FAQ.

• Why AICodePilot
• Features
• Screenshots and Demo
• Quick Start
• Usage Guide
• Architecture
• Agent Runtime
• Tech Stack
• Project Structure
• Configuration
• Agent Development Guide
• API Reference
• Deployment and Production
• Testing and Quality
• Security Model
• Roadmap
• FAQ
• Contributing
• License

Modern coding assistants are most useful when they can inspect the same project context as the developer. AICodePilot is designed around that idea:

• For beginners: ask natural-language questions about a repository and get answers grounded in files, line references, and tool results.
• For working developers: trace where logic lives, search code semantically, analyze logs, and request safe patch suggestions without giving the Agent broad write access.
• For AI Agent builders: study a compact, test-covered implementation of tool calling, RAG, model provider abstraction, memory, streaming events, and frontend evidence panels.
• For teams evaluating local AI workflows: run the full stack locally or through Docker Compose, keep API keys client-provided, and leave shell execution disabled by default.

• 🧠 Agentic coding loop: a single-agent executor uses native OpenAI-compatible tool calling first, with a text-protocol fallback for providers that do not support function calling.
• 🔎 Codebase RAG: indexes local repositories, chunks source files by line ranges, embeds code, stores vectors, retrieves Top-K matches, and reranks results with code-aware signals.
• 🧰 Safe tool registry: built-in tools cover file listing, file reading, project trees, filename search, text search, code retrieval, log analysis, and diff-only patch proposals.
• 🛡️ Security-first defaults: path traversal checks, binary/large-file guards, bounded tool steps, optional shell execution, command allowlists, timeouts, and output truncation.
• 🔌 Provider abstraction: backend support currently includes openai and deepseek; per-request API keys and base URLs can override .env without mutating global settings.
• 🔑 Bring your own key: the frontend stores provider keys in browser localStorage; the backend uses them only for the current request and does not persist them.
• 🧾 Traceable answers: responses can include tool calls, code references, retrieved snippets, scores, and patch suggestions for easier verification.
• 📡 SSE Agent events: /api/chat/stream emits thinking, tool_start, tool_end, done, and error events so the UI can show Agent progress.
• 💬 Short-term memory: conversation_id keeps bounded in-memory context while SQLite stores user/assistant message history.
• 🖥️ Three-column workspace: Model Center, Workspace indexing, Chat, Agent Trace, and Code Evidence live in one Next.js interface.
• 🐳 Local or Docker: run with a PowerShell helper script, manual backend/frontend commands, or Docker Compose with host project path mapping.
• ✅ Regression coverage: backend tests cover Agent behavior, providers, tools, RAG, API routes, memory, database persistence, and streaming; frontend tests cover core UI behavior.

The repository does not currently include committed screenshots or GIFs. Because AICodePilot has a real UI, adding visual assets will make the GitHub landing page much more effective.

Recommended assets:

Suggested Markdown once assets are added:

![AICodePilot workspace](docs/assets/workspace.png)

git clone <your-repository-url>
cd ai-code-pilot

Copy-Item .env.example .env

At minimum, configure one chat provider:

# OpenAI
LLM_PROVIDER=openai
OPENAI_API_KEY=your_openai_api_key
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-5.2

# Or DeepSeek
LLM_PROVIDER=deepseek
DEEPSEEK_API_KEY=your_deepseek_api_key
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-v4-pro

For local-first code search without an embedding API key, use:

EMBEDDING_PROVIDER=local

Note: .env.example currently sets EMBEDDING_PROVIDER=openai, while the code default is local. If you want zero-key local embeddings, set EMBEDDING_PROVIDER=local explicitly.

On Windows / PowerShell:

powershell -ExecutionPolicy Bypass -File scripts/start-local.ps1

First run with dependency installation:

powershell -ExecutionPolicy Bypass -File scripts/start-local.ps1 -Install

Then open:

The startup script opens separate PowerShell windows for the backend and frontend. Stop either service with Ctrl+C in its terminal window.

1. Open http://localhost:3000.
2. Select OpenAI or DeepSeek in Model Center.
3. Enter your API key or rely on .env credentials.
4. Set a backend-visible project path in Workspace.
5. Click Index Workspace.
6. Ask:

Where is the Agent execution flow implemented? Cite the files you used.

Backend:

cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python -m uvicorn app.main:app --reload

Frontend:

cd frontend
npm install
npm run dev

If backend dependency installation fails because httpx2 cannot be resolved, replace httpx2 with httpx in backend/requirements.txt. The source code imports httpx.

The UI is designed as a developer cockpit:

Useful prompts:

Explain the backend architecture in this repository.

Find the FastAPI route that handles streaming chat and explain the event format.

Analyze this error log and suggest the most likely source file:
<paste log here>

Suggest a safe patch for the provider model discovery flow. Do not modify files.

Health check:

curl http://localhost:8000/api/health

Synchronous Agent chat:

curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Where is configuration loaded?",
    "project_path": "D:/MyWork/Code/ai-code-pilot",
    "provider": "deepseek",
    "model": "deepseek-v4-pro"
  }'

Index a project for RAG:

curl -X POST http://localhost:8000/api/projects/index \
  -H "Content-Type: application/json" \
  -d '{
    "project_path": "D:/MyWork/Code/ai-code-pilot"
  }'

Search indexed code:

curl -X POST http://localhost:8000/api/projects/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "tool registry design",
    "top_k": 5
  }'

Fetch provider models with a user-supplied key:

curl -X POST http://localhost:8000/api/providers/models \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "api_key": "your_api_key",
    "base_url": "https://api.openai.com/v1"
  }'

POST /api/chat/stream returns Server-Sent Events:

event: thinking
data: {"step":1}

event: tool_start
data: {"tool":"read_file","arguments":{"file_path":"backend/app/main.py"}}

event: tool_end
data: {"tool":"read_file","error":null}

event: done
data: {"answer":"...","conversation_id":"...","tool_calls":[...],"references":[...]}

The frontend consumes POST-based SSE with fetch and ReadableStream in frontend/lib/sse.ts, because the browser-native EventSource API only supports GET.

The backend also keeps a minimal CLI entry:

cd backend
python -m app.main --project-path ..

AICodePilot is split into five practical layers:

1. Experience layer: Next.js workspace for model configuration, project indexing, chat, trace, and evidence review.
2. API layer: FastAPI routes for chat, streaming, project indexing/search, model discovery, health checks, and session history.
3. Agent runtime: an executor that manages tool-calling steps, loop detection, final answer synthesis, memory, and result extraction.
4. Tool and retrieval layer: safe tools for files/search/logs/patches plus a RAG pipeline for repository evidence.
5. Persistence layer: SQLite for conversations and Chroma/JSON/memory vector stores for retrieval data.

Instead of one dense all-in-one diagram, the architecture is shown as three readable views:

flowchart LR
  classDef client fill:#eef6ff,stroke:#2563eb,stroke-width:1px,color:#0f172a;
  classDef api fill:#f0fdf4,stroke:#16a34a,stroke-width:1px,color:#0f172a;
  classDef agent fill:#fff7ed,stroke:#ea580c,stroke-width:1px,color:#0f172a;
  classDef model fill:#faf5ff,stroke:#9333ea,stroke-width:1px,color:#0f172a;
  classDef data fill:#f8fafc,stroke:#64748b,stroke-width:1px,color:#0f172a;

  User["Developer"]:::client --> UI["Next.js workspace<br/>Model Center · Chat · Trace · Evidence"]:::client

  UI --> API["FastAPI API<br/>chat · stream · projects · models · sessions"]:::api

  API --> Agent["Agent runtime<br/>executor · memory · events · finalizer"]:::agent

  Agent --> Tools["Safe tools<br/>files · search · logs · retrieve_code · propose_patch"]:::agent
  Agent --> Providers["LLM providers<br/>OpenAI · DeepSeek"]:::model

  Tools --> Repo["Local repository<br/>source files · logs · project tree"]:::data
  Tools --> RAG["Code RAG<br/>index · chunk · embed · retrieve · rerank"]:::data

  API --> SQLite[("SQLite<br/>conversation history")]:::data
  RAG --> VectorStore[("Vector store<br/>Chroma · JSON · memory")]:::data
  Providers --> Remote["OpenAI-compatible<br/>chat completions API"]:::model

flowchart LR
  Start(["User asks a repository-aware question"])
  Request["Build AgentRequest<br/>message + project_path + provider + model"]
  Context["Build context<br/>system prompt + recent memory + tool schemas"]
  LLM["Call provider<br/>chat_with_tools"]
  Decision{"Model response"}
  ToolCall["Tool call requested"]
  Dispatch["ToolRegistry dispatch<br/>validate args + inject project_path"]
  Result["ToolResult<br/>structured data or error"]
  Continue["Append result to model context"]
  Final["Final answer returned"]
  Clean["Clean answer<br/>extract references + patch suggestions"]
  Persist["Persist messages<br/>SQLite + bounded memory"]
  Response(["Return JSON or SSE done event"])

  Start --> Request --> Context --> LLM --> Decision
  Decision -->|tool_calls| ToolCall --> Dispatch --> Result --> Continue --> LLM
  Decision -->|final content| Final --> Clean --> Persist --> Response

Agent safeguards in this loop:

flowchart LR
  Project["Backend-visible<br/>project path"]
  Scan["ProjectIndexer<br/>scan supported files"]
  Filter["Skip ignored content<br/>.git · node_modules · build · cache · tests"]
  Chunk["CodeChunker<br/>80-line chunks + overlap"]
  Embed{"Embedding provider"}
  Local["Local hash embeddings<br/>zero external key"]
  OpenAIEmb["OpenAI embeddings<br/>semantic vectors"]
  Store["Vector store<br/>Chroma · JSON · memory"]
  Query["User query or<br/>retrieve_code tool"]
  Retrieve["Top-K retrieval"]
  Rerank["Hybrid rerank<br/>tokens · paths · source priority"]
  Evidence["Code evidence<br/>file path · lines · snippet · score"]

  Project --> Scan --> Filter --> Chunk --> Embed
  Embed -->|EMBEDDING_PROVIDER=local| Local --> Store
  Embed -->|EMBEDDING_PROVIDER=openai| OpenAIEmb --> Store
  Query --> Retrieve --> Store
  Store --> Retrieve --> Rerank --> Evidence

The current implementation is a single-agent system. It does not implement multi-agent collaboration yet. The design is intentionally compact and inspectable:

Important runtime behavior:

• AGENT_MAX_STEPS defaults to 10 and is validated between 3 and 30.
• Native tool calling is preferred through chat_with_tools.
• If a provider does not support tool calling, the executor can fall back to a text protocol parser.
• Identical back-to-back tool calls are detected to reduce runaway loops.
• Tool payloads are excluded from rolling memory; only the raw user message and final assistant answer are remembered.
• answer_delta is reserved in the event schema, but current streaming is step/tool-event oriented rather than token-level streaming.

.
|-- backend/
|   |-- app/
|   |   |-- agent/      # Agent facade, executor, planner, prompts, schemas, events
|   |   |-- api/        # FastAPI routers and request/response schemas
|   |   |-- core/       # settings, logging, exceptions, filesystem safety
|   |   |-- db/         # SQLModel models, engine, repository
|   |   |-- llm/        # provider abstraction, OpenAI, DeepSeek, HTTP client
|   |   |-- memory/     # bounded conversation memory and session store
|   |   |-- rag/        # indexer, chunker, embeddings, vector store, retriever
|   |   `-- tools/      # safe tools for files, search, logs, RAG, shell, patches
|   |-- tests/          # backend test suite
|   |-- Dockerfile
|   `-- requirements.txt
|-- frontend/
|   |-- app/            # Next.js app entry and global styles
|   |-- components/     # workspace UI, model selector, timeline, evidence panels
|   |-- hooks/          # chat, provider config, auth demo, workspace import
|   |-- lib/            # typed API client and SSE parser
|   |-- tests/          # frontend tests
|   |-- Dockerfile
|   `-- package.json
|-- docs/               # architecture, API, deployment, security, Agent, RAG docs
|-- scripts/
|   `-- start-local.ps1 # local full-stack startup helper
|-- data/               # runtime data directory, ignored except .gitkeep
|-- .github/workflows/  # CI workflow
|-- docker-compose.yml
|-- pyproject.toml
|-- pytest.ini
|-- .env.example
`-- README.md

Configuration is loaded from environment variables and .env.

1. Create a new tool class under backend/app/tools/.
2. Subclass BaseTool.
3. Define name, description, an argument schema, and run(...).
4. Register it in create_default_registry() in backend/app/tools/registry.py.
5. Add tests under backend/tests/.

Minimal shape:

from pydantic import BaseModel, Field

from app.tools.base import BaseTool


class MyToolArgs(BaseModel):
    query: str = Field(..., description="What to inspect")


class MyTool(BaseTool):
    name = "my_tool"
    description = "Describe what this tool does and when the Agent should use it."
    args_schema = MyToolArgs

    def run(self, query: str) -> dict[str, object]:
        return {"query": query, "result": "structured data only"}

Tool design tips:

• Return structured JSON-friendly data, not long prose.
• Keep filesystem operations inside the project root.
• Add explicit size limits and timeouts for expensive operations.
• Prefer read-only behavior unless the user explicitly reviews and approves changes.

1. Implement a provider under backend/app/llm/.
2. Subclass BaseLLMProvider.
3. Implement chat(...) and, ideally, chat_with_tools(...).
4. Register the provider in LLMProviderFactory.
5. Add configuration fields in backend/app/core/config.py.
6. Add tests similar to the OpenAI and DeepSeek provider tests.

Current provider implementation expects OpenAI-compatible chat completions. A provider without function-calling support can still work through the fallback text protocol, but native tool calling gives better Agent reliability.

The RAG pipeline is intentionally modular:

More detailed docs:

• API
• Streaming Protocol
• Model Discovery
• Agent Design
• RAG Design
• Security

Copy-Item .env.example .env
docker compose up --build

Docker path mapping matters. The backend can only index paths visible inside the container. Configure:

PROJECTS_HOST_ROOT=D:/code/my_projects
PROJECTS_CONTAINER_ROOT=/workspace
NEXT_PUBLIC_DEFAULT_PROJECT_PATH=/workspace
VECTOR_STORE_PATH=/app/data/vector_store

Then use /workspace/... as the project path in the UI or API.

• Keep ENABLE_SHELL_TOOL=false unless running in a trusted, isolated environment.
• Store real secrets in your deployment platform, not in committed files.
• Restrict CORS_ALLOWED_ORIGINS to the deployed frontend origin.
• Mount persistent volumes for SQLite and vector store data.
• Add production authentication before exposing the app beyond a trusted local network.
• Review provider key handling if moving from BYOK local usage to team-managed credentials.
• Add frontend build/test gates to CI if the UI becomes part of production release criteria.
• Add screenshots, release notes, issue templates, and a public CI badge before publishing widely.

Backend:

pytest backend/tests
ruff check .
black --check .
mypy backend/app

Frontend:

cd frontend
npm run typecheck
npm run lint
npm run test
npm run build

Current GitHub Actions workflow runs backend quality gates on pushes and pull requests to main:

• ruff check .
• black --check .
• mypy backend/app
• pytest backend/tests

AICodePilot works with local code, so the default posture is conservative:

• File tools validate project-root boundaries and reject path traversal.
• read_file blocks binary files and oversized reads.
• RAG indexing skips .git, virtual environments, node_modules, build outputs, caches, temporary directories, and tests.
• run_command is disabled unless ENABLE_SHELL_TOOL=true.
• The shell tool uses shell=False, command allowlists, project-root working directory checks, timeouts, and output limits.
• propose_patch returns unified diff suggestions only; it does not write files.
• Browser-stored API keys are sent per request and are not persisted by the backend.
• The current frontend auth/profile/captcha flow is a local demo, not production authentication.

Read more in docs/security.md.

Based on the current repository docs and implementation state:

• Add backend providers for Qwen, GLM, Claude, Gemini, Moonshot, and other OpenAI-compatible vendors.
• Improve repository intelligence with dependency graphs, call graphs, framework detection, and security scan hooks.
• Expand patch workflows from diff suggestion to reviewable multi-file patch plans.
• Replace demo-only frontend auth with real backend authentication and user/session management.
• Add stronger frontend regression coverage and include frontend gates in CI.
• Improve large-project import limits, progress reporting, and browser-side warnings.
• Add official screenshots, GIF demos, release checklist, and public repository metadata.

Contributions are welcome. Good contributions keep the Agent reliable, observable, and safe.

Suggested workflow:

1. Fork the repository and create a focused branch.
2. Read Development Guide, Agent Design, and Security.
3. Keep changes scoped; avoid unrelated refactors.
4. Add or update tests for backend behavior changes.
5. Add frontend tests or manual verification notes for UI changes.
6. Run the relevant quality gates before opening a pull request.
7. In the PR description, include the motivation, changed files, verification commands, and known risks.

Recommended commit style:

feat: add provider model discovery
fix: harden project path normalization
docs: refresh quick start guide
test: cover streaming chat events

• Architecture
• Agent Design
• RAG Design
• API
• Streaming Protocol
• Model Discovery
• Security
• Deployment
• User Guide
• Development Guide
• Roadmap / Todo

AICodePilot is released under the MIT License.

Maintained by AICodePilot contributors.

Before publishing this repository publicly, consider adding:

• Public GitHub repository URL and CI badge
• Maintainer GitHub handles
• Issue templates and pull request template
• Discussions or community channel
• Screenshots and release assets