Cortex

Cortex is an open-source agent workspace built for operating inside a real project folder instead of stopping at chat. It combines a React frontend, a FastAPI backend, scoped file access, persistent conversation state, and sandboxed shell execution so the agent can inspect files, take actions, and surface everything it does.

Screenshots

Workspace and analysis flow

Tool execution and artifact creation

File update workflow

Core Capabilities

• Runs a ReAct-style agent loop that can reason, choose tools, execute actions, and continue from results
• Restricts file access to the selected working directory
• Supports file read, write, list, and search operations
• Routes shell execution through Docker when available, with approval controls and host fallback
• Streams progress, tool calls, artifacts, diffs, and file updates to the UI in real time
• Persists conversations in SQLite
• Includes a TEST/ workspace for repeatable demos and prompt validation

Repository Structure

Co-Work/
|-- backend/
|   |-- src/
|   |   |-- agent/
|   |   |-- llm/
|   |   |-- models/
|   |   |-- sandbox/
|   |   |-- tools/
|   |   |-- config.py
|   |   |-- database.py
|   |   `-- main.py
|   |-- tests/
|   |-- Dockerfile.sandbox
|   |-- pyproject.toml
|   `-- README.md
|-- frontend/
|   |-- public/
|   |-- src/
|   |   |-- hooks/
|   |   |-- utils/
|   |   |-- App.jsx
|   |   |-- index.css
|   |   `-- main.jsx
|   |-- package.json
|   `-- vite.config.js
|-- docs/
|-- TEST/
`-- README.md

System Architecture

graph TB
    subgraph Frontend["Frontend (React + Vite)"]
        Chat[Chat Workspace]
        Files[File Tree and Preview]
        Progress[Progress and Artifacts]
        WSClient[WebSocket Hook]
        RESTClient[REST API Helpers]
    end

    subgraph Backend["Backend (FastAPI + Python)"]
        API[REST and WebSocket API]
        Agent[Agent Loop]
        Context[Agent Context]
        LLM[Gemini Provider]
        Tools[Tool Registry]
        DB[(SQLite Conversations)]
        Sandbox[Docker Sandbox Manager]
    end

    subgraph Tooling["Tools"]
        FileRead[file_read]
        FileWrite[file_write]
        FileList[file_list]
        FileSearch[file_search]
        ShellExec[shell_exec]
        WebSearch[web_search]
    end

    Chat -->|messages| WSClient
    Files --> RESTClient
    Progress --> WSClient
    WSClient -->|WebSocket| API
    RESTClient -->|HTTP| API
    API --> Agent
    Agent --> Context
    Agent --> LLM
    Agent --> Tools
    Agent --> DB
    Tools --> FileRead
    Tools --> FileWrite
    Tools --> FileList
    Tools --> FileSearch
    Tools --> ShellExec
    Tools --> WebSearch
    ShellExec --> Sandbox
    API -->|streamed results| WSClient

Loading

Backend APIs

REST Endpoints

• GET /api/health: basic service health check.
• GET /api/conversations: list saved conversations.
• GET /api/conversations/{id}: fetch one saved conversation.
• DELETE /api/conversations/{id}: delete a saved conversation.
• GET /api/folder/drives: list available drive roots for the folder browser.
• GET /api/folder/cwd: return the default starting path for the folder browser.
• POST /api/folder/select: validate a selected folder and return summary metadata.
• POST /api/folder/browse: list the contents of a directory for the folder browser.
• GET /api/file/preview?path=...&working_dir=...: preview a file inside the active workspace.

WebSocket Channel

Endpoint:

• ws://localhost:8000/ws/chat

Client to server events:

• user_message: submit a prompt with working directory and optional conversation id.
• approval_response: approve or deny a pending shell command.
• cancel: stop the current agent run.

Server to client events:

• thinking: indicates the agent has started processing.
• assistant_chunk: streamed assistant text.
• assistant_done: end of assistant streaming.
• tool_call: tool invocation metadata for the UI.
• tool_result: tool output, status, and optional diff data.
• approval_request: explicit approval request for guarded commands.
• file_changed: artifact and file update notification.
• file_tree_update: real-time filesystem update event.
• conversation_created: newly created conversation id.
• sandbox_status: Docker or host execution status line.
• error: execution or orchestration error.

Execution Flow

1. User selects a folder in the frontend.
2. Frontend validates and browses it through REST endpoints.
3. User sends a prompt over WebSocket.
4. Backend creates or resumes conversation context.
5. Agent loop calls the model with tool declarations and message history.
6. If the model requests a tool, the backend validates and executes it.
7. File tools stay scoped to the selected folder.
8. Shell commands require approval and prefer Docker sandbox execution.
9. Results stream back as tool events, progress updates, artifact changes, and assistant text.
10. Conversation state is persisted for later reload.

Running Locally

Backend

cd backend
pip install uv
uv sync
uv run uvicorn src.main:app --reload --port 8000

Frontend

cd frontend
npm install
npm run dev

Open http://localhost:5173, connect a folder, and start a session.

Demo Workspace

The TEST/ directory is intentionally kept in the repository as a working demo dataset. It is useful for validating file reads, file writes, analysis tasks, and artifact generation without having to prepare a sample project first.

Current State

Cortex already supports the core agent workflow end to end: folder-scoped file operations, shell execution with sandbox support, persistent conversations, live progress updates, diff-aware file changes, and artifact previews. The root README is intended as the full project overview, while the backend README stays focused on backend runtime behavior.