/chromadb/agent-harness/CHROMADB.md

Agent Harness: ChromaDB Vector Database CLI

Purpose

This harness provides a standard operating procedure (SOP) and toolkit for coding agents (Claude Code, Codex, etc.) to interact with ChromaDB vector databases via a unified CLI interface. The goal: let AI agents query, manage, and populate vector knowledge bases without needing a browser UI or Python SDK boilerplate.

Backend Description

ChromaDB HTTP API v2 running at http://localhost:8000 (configurable via --host).

• Tenant: default_tenant
• Database: default_database
• Protocol: REST/JSON over HTTP
• Client: Python requests library wrapping all API endpoints

ChromaDB is a stateless vector database -- no session or connection state is maintained between CLI invocations. Each command makes independent HTTP calls.

Architecture

agent-harness/
├── setup.py                          # Package setup with click, prompt-toolkit, requests
├── CHROMADB.md                       # This file -- SOP and architecture
└── cli_anything/
    └── chromadb/
        ├── __init__.py
        ├── __main__.py               # python -m entry point
        ├── README.md                 # Usage docs
        ├── chromadb_cli.py           # Click CLI + REPL dispatcher
        ├── core/
        │   ├── __init__.py
        │   ├── collections.py        # list, create, delete, info
        │   ├── documents.py          # add, get, delete, count
        │   ├── query.py              # semantic search
        │   └── server.py             # heartbeat, version
        ├── utils/
        │   ├── __init__.py
        │   ├── chromadb_backend.py   # HTTP client for ChromaDB v2 API
        │   └── repl_skin.py          # Unified REPL skin
        ├── skills/
        │   └── SKILL.md
        └── tests/
            ├── __init__.py
            ├── TEST.md               # Test plan and results
            ├── test_core.py          # Unit tests (mocked HTTP)
            └── test_full_e2e.py      # E2E tests (real ChromaDB)

Command Groups

server

Server health and metadata commands.

Command	Description
server heartbeat	Check ChromaDB server health (returns nanosecond timestamp)
server version	Get ChromaDB server version string

collection

Collection CRUD operations.

Command	Description
collection list	List all collections with IDs and metadata
collection create --name NAME	Create a new collection
collection delete --name NAME	Delete a collection by name
collection info NAME	Get detailed info about a collection

document

Document management within collections.

Command	Description
document add --collection C --id ID --document TEXT	Add document(s) to a collection
document get --collection C	Get documents (with optional --id, --limit, --offset)
document delete --collection C --id ID	Delete document(s) by ID
document count --collection C	Count documents in a collection

query

Semantic search against collections.

Command	Description
query search --collection C --text T	Semantic search with optional --n-results

State Model

Stateless. Every CLI invocation creates a fresh HTTP session and queries the ChromaDB API directly. There is no local state file, no session persistence, and no undo/redo. The ChromaDB server itself is the single source of truth.

This means:

• Commands are idempotent where the underlying API supports it
• No risk of stale local state
• Every command can be run independently in any order
• REPL mode maintains only the backend URL and output format preference in memory

API Endpoints Used

All under ChromaDB v2 API (/api/v2/):

Endpoint	Method	Command
/api/v2/heartbeat	GET	server heartbeat
/api/v2/version	GET	server version
/api/v2/tenants/{t}/databases/{d}/collections	GET	collection list
/api/v2/tenants/{t}/databases/{d}/collections	POST	collection create
/api/v2/tenants/{t}/databases/{d}/collections/{name}	GET	collection info
/api/v2/tenants/{t}/databases/{d}/collections/{name}	DELETE	collection delete
/api/v2/tenants/{t}/databases/{d}/collections/{id}/add	POST	document add
/api/v2/tenants/{t}/databases/{d}/collections/{id}/get	POST	document get
/api/v2/tenants/{t}/databases/{d}/collections/{id}/delete	POST	document delete
/api/v2/tenants/{t}/databases/{d}/collections/{id}/count	POST	document count
/api/v2/tenants/{t}/databases/{d}/collections/{id}/query	POST	query search

Output Formats

All commands support dual output modes controlled by the --json flag:

• Human-readable (default): Colored tables, status lines, and formatted text via ReplSkin
• Machine-readable (--json): Structured JSON on stdout for agent consumption

Current Collections (Hub)

• hub_knowledge -- Main knowledge base with 230+ indexed documents
• team -- Team information collection

Testing Strategy

Two test suites with complementary purposes:

1. Unit tests (test_core.py): Mocked HTTP calls via unittest.mock. Tests CLI argument parsing, output formatting, URL construction, and error handling. Fast, deterministic, no external dependencies.
2. E2E tests (test_full_e2e.py): Real subprocess calls to the installed CLI binary against a live ChromaDB at localhost:8000. Tests actual JSON output parsing, exit codes, and end-to-end command execution.

Key Principles

• Stateless by design -- No local state to get out of sync with the server
• JSON output for agents -- Every command supports --json for machine parsing
• Fail loudly -- Connection errors and bad responses produce clear error messages
• Leverage the HTTP API directly -- No ChromaDB Python SDK dependency, just requests