Core Agent Loop API

FastAPI application providing Server-Sent Events (SSE) endpoint for Claude SDK agent interactions.

Project Structure

core_agent_loop/
├── app/
│   ├── __init__.py
│   ├── main.py                 # FastAPI application entry point
│   └── router/
│       ├── __init__.py
│       └── agent.py            # Agent loop SSE endpoint
├── config.py                   # Configuration settings
├── add_keyword_test.py         # Original test script
├── requirements.txt            # Python dependencies
└── env.local                   # Configuration file (rename to .env)

Setup

Install dependencies:
```
pip install -r requirements.txt
```

Configure environment:

cp env.local .env
# Edit .env to add your Langfuse credentials if needed

Ensure Claude CLI is installed and configured:
```
claude --version
```

Running the Server

Using Docker Compose (Recommended):

# Start all services (FastAPI on 8334, Claude-Mem Manager on 37777, File API on 38888)
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

The FastAPI server will be available at http://localhost:8334
The Claude-Mem Manager UI will be available at http://localhost:37777/switch_user
All other traffic on port 37777 will be proxied to the active claude-mem worker
The File API service will be available at http://localhost:38888 The CLI wheel server will be available at http://localhost:11113

Using Python directly:

python -m app.main

Using Uvicorn:

uvicorn app.main:app --reload --host 0.0.0.0 --port 8334

The server will start at http://localhost:8334

CLI Auto Upgrade

Install from PyPI:

python -m pip install --upgrade pip
python -m pip install --upgrade luckee-cli

If you want to validate a dev publish first, install from TestPyPI:

python -m pip install --upgrade \
  --index-url https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple \
  luckee-cli

For the staging CLI, set the environment before login/use:

export LUCKEE_ENV=staging

This selects both the staging OAuth API (staging-user-api.motse.ai) and the staging frontend automatically. LUCKEE_OAUTH_BASE_URL / LUCKEE_FRONTEND can still override individual URLs when needed.

CLI auth helpers:

luckee login
luckee logout

Published defaults:

LUCKEE_ENV=staging → OAuth API staging-user-api.motse.ai, frontend luckee-frontend-staging-…
LUCKEE_ENV=prod (default) → OAuth API user-api.motse.ai, frontend motse.ai
dev branch builds default WebSocket endpoint to wss://core-agent-loop-dev-950663559455.us-central1.run.app/api/v2/agent/ws
main branch builds default WebSocket endpoint to wss://core-agent-loop-950663559455.us-central1.run.app/api/v2/agent/ws
dev branch builds default File API base URL to https://file-api-dev-950663559455.us-central1.run.app
main branch builds default File API base URL to https://file-api-main-950663559455.us-central1.run.app

Upgrade the installed CLI:

luckee --upgrade

Or while inside interactive CLI:

/upgrade

CLI Development

For local luckee CLI development and packaging validation, use the dedicated guide:

CLI Development Guide

Shortest repeatable local validation loop:

conda activate core_agent_loop
python scripts/validate_cli_dev_loop.py

That helper repairs stale editable CLI metadata, validates both local entrypoints, and builds a fresh wheel. Use python scripts/validate_cli_dev_loop.py --with-pipx --remote-smoke ... when you also want packaged remote validation.

API Endpoints

Root

GET / - API information and available endpoints

Health Check

GET /health - Health check endpoint

Agent Test

GET /api/agent/test - Test the agent router

Agent Stream (SSE)

POST /api/agent/stream - Stream agent responses via Server-Sent Events

Request Body:

{
  "query": "add a keyword test_keyword_1",
  "thread_id": null,
  "user_id": "dylan",
  "working_dir": null,
  "system_prompt": null
}

Response: Server-Sent Events stream with structured state messages.

File API (Port 38888)

GET /api/v2/resume_thread - Resume a thread by streaming messages (SSE)
GET /api/v2/list_threads - List all thread IDs for a user
GET /api/v2/fetch_files - Fetch files from user directories

Resume Thread (SSE) Query Parameters:

thread_id: Thread ID (must be a valid UUID)
user_id: User ID

Resume Thread Example:

curl -N "http://localhost:38888/api/v2/resume_thread?thread_id=550e8400-e29b-41d4-a716-446655440000&user_id=dylan"

The stream always starts with a config message containing metadata from working_dir/metadata.json, followed by all messages from streaming_messages.jsonl, and ends with a completion event.

List Threads Query Parameters:

user_id: User ID

List Threads Example:

curl "http://localhost:38888/api/v2/list_threads?user_id=dylan"

Fetch Files Query Parameters:

type: Type of file to fetch (csv, json, or json_folder)
thread_id: Thread ID (must be a valid UUID string)
path: Relative path to the file from working_dir
user_id: User ID

Examples:

Fetch a JSON file:

curl "http://localhost:38888/api/v2/fetch_files?type=json&thread_id=550e8400-e29b-41d4-a716-446655440000&path=data/config.json&user_id=dylan"

Fetch a CSV file:

curl "http://localhost:38888/api/v2/fetch_files?type=csv&thread_id=550e8400-e29b-41d4-a716-446655440000&path=data/report.csv&user_id=dylan"

Fetch all JSON files from a folder:

curl "http://localhost:38888/api/v2/fetch_files?type=json_folder&thread_id=550e8400-e29b-41d4-a716-446655440000&path=data/json_files&user_id=dylan"

Response Format:

For csv/json: Returns content of the file
For json_folder: Returns a dict mapping filename to content for all *.json files

Security:

Path traversal protection is enforced
Files must exist under /data/{user_id}/projects/{thread_id}/working_dir/{path}

Session Management

The agent supports session resumption based on thread_id. The project state (including the Claude SDK session ID) is stored in /data/${user_id}/projects/${thread_id}/working_dir/metadata.json.

To resume a session, include the thread_id in subsequent requests:

{
  "query": "continue with the next task",
  "thread_id": "previous_thread_id",
  "user_id": "dylan"
}

If a thread_id is provided but no existing session is found in the project metadata, the API will return an error.

Development

Architecture Documentation

For detailed information about the system architecture, modules, and design patterns, see:

Architecture Documentation - Complete system architecture overview

Original Test Script

The original CLI test script is still available:

python add_keyword_test.py --query "add a keyword test_keyword_1"

License

MIT

Metadata

Release files for luckee-cli 0.1.20260319045732160

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for luckee-cli 0.1.20260319045732160
File	Size	Uploaded
luckee_cli-0.1.20260319045732160.tar.gz	51.0 kB	Mar 19, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for luckee-cli 0.1.20260319045732160
File	Interpreter	ABI	Platform	Reset
luckee_cli-0.1.20260319045732160-py3-none-any.whl 49.0 kB Mar 19, 2026	Python 3	none	any	Details

Total release size: 100.0 kB

Release files / luckee_cli-0.1.20260319045732160.tar.gz

Download URL	luckee_cli-0.1.20260319045732160.tar.gz
Size	51.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`352f4e4f0af45bc151507d0684884fa3b5a7cfd4937c242247ac53a1bf44b77f`
BLAKE2b-256 checksum How to use checksums	`53873e91fce22d6e9b9d92e6dc8b446662d92ec407094c8c9c73bb5070be016b`
Upload date	Mar 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/motse-ai/core_agent_loop
Publishing commit: github.com/motse-ai/core_agent_loop/tree/223ae6bd979e12930914dc205845f3fd6b3104ca

Workflow

Publishing configuration: github.com/motse-ai/core_agent_loop/blob/223ae6bd979e12930914dc205845f3fd6b3104ca/.github/workflows/cli-daily-release.yml
Publishing logs: github.com/motse-ai/core_agent_loop/actions/runs/23280515928/attempts/1

Artifact

Subject: luckee_cli-0.1.20260319045732160.tar.gz
SHA-256 checksum: 352f4e4f0af45bc151507d0684884fa3b5a7cfd4937c242247ac53a1bf44b77f Verifying attestations

Release files / luckee_cli-0.1.20260319045732160-py3-none-any.whl

Download URL	luckee_cli-0.1.20260319045732160-py3-none-any.whl
Size	49.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`10f9a23d3fc402de22c37d5428314abc11e5094347585ccb313c174de5cefe0e`
BLAKE2b-256 checksum How to use checksums	`b27ccc7df46b9c192b093646f8c85a8d73c295d63c6cf459a080d6a6a84c3542`
Upload date	Mar 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/motse-ai/core_agent_loop
Publishing commit: github.com/motse-ai/core_agent_loop/tree/223ae6bd979e12930914dc205845f3fd6b3104ca

Workflow

Publishing configuration: github.com/motse-ai/core_agent_loop/blob/223ae6bd979e12930914dc205845f3fd6b3104ca/.github/workflows/cli-daily-release.yml
Publishing logs: github.com/motse-ai/core_agent_loop/actions/runs/23280515928/attempts/1

Artifact

Subject: luckee_cli-0.1.20260319045732160-py3-none-any.whl
SHA-256 checksum: 10f9a23d3fc402de22c37d5428314abc11e5094347585ccb313c174de5cefe0e Verifying attestations