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 publish, set staging auth environment variables before login/use:
export LUCKEE_OAUTH_BASE_URL="https://staging-user-api.motse.ai/luckee/user/"
export LUCKEE_FRONTEND="https://luckee-frontend-staging-950663559455.us-central1.run.app"
CLI auth helpers:
luckee login
luckee logout
Published defaults:
devbranch builds default OAuth frontend tohttps://luckee-frontend-staging-950663559455.us-central1.run.appmainbranch builds default OAuth frontend tohttps://motse.aidevbranch builds default WebSocket endpoint towss://core-agent-loop-dev-950663559455.us-central1.run.app/api/v2/agent/wsmainbranch builds default WebSocket endpoint towss://core-agent-loop-950663559455.us-central1.run.app/api/v2/agent/wsdevbranch builds default File API base URL tohttps://core-agent-loop-dev-950663559455.us-central1.run.appmainbranch builds default File API base URL tohttps://file-api-main-950663559455.us-central1.run.app
Upgrade the installed CLI:
luckee --upgrade
Or while inside interactive CLI:
/upgrade
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, orjson_folder)thread_id: Thread ID (must be a valid UUID string)path: Relative path to the file from working_diruser_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*.jsonfiles
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
1 maintainer
Metadata
1 maintainer
Release files for luckee-cli 0.1.20260316170537104
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| luckee_cli-0.1.20260316170537104.tar.gz | 27.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| luckee_cli-0.1.20260316170537104-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 53.5 kB
Release files / luckee_cli-0.1.20260316170537104.tar.gz
| Download URL | luckee_cli-0.1.20260316170537104.tar.gz |
|---|---|
| Size | 27.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fa25a34bba5a88dfff91a06d0623d69f0a704931419a095efa2602bd7cc19bca
|
|
BLAKE2b-256 checksum How to use checksums |
5ffb14eea6f4933401dbc73d90372f362a4744c253375ef66118c7d512adf4be
|
| Upload date | |
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 16, 2026.
Transparency logRelease files / luckee_cli-0.1.20260316170537104-py3-none-any.whl
| Download URL | luckee_cli-0.1.20260316170537104-py3-none-any.whl |
|---|---|
| Size | 25.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
22462a86ea919d95cc7aca1177f99f4da6cdeecfb8ca1392276a483bb6f73765
|
|
BLAKE2b-256 checksum How to use checksums |
1211626a7b5ee143c6b9ced2983b92cc934bc7412ba474f2bb7d737a7cc474ae
|
| Upload date | |
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 16, 2026.
Transparency log
