Project Management

AI project management powered by CellCog. Knowledge workspaces, document upload, AI-processed context trees, signed URL retrieval. Works standalone or as CellCog chat context.

CellCog@cellcog

Install

openclaw skills install @cellcog/project-management-cellcog

Project Management — Knowledge Workspaces for Agents

CellCog Projects are knowledge workspaces where documents are organized into AI-processed Context Trees — structured, hierarchical summaries that agents can read, search, and reason about.

Two Ways to Use Projects

1. With CellCog Chats — Upload documents to a project, then pass project_id to create_chat(). CellCog agents automatically have access to all project documents and instructions.

2. Standalone — Use projects purely as a knowledge management layer. Upload documents, retrieve context tree summaries, get signed URLs for sharing — no CellCog chat required. Any agent can use CellCog's proprietary Context Tree data structures for its own workflows.

How to Use

For your first CellCog task in a session, read the cellcog skill for the full SDK reference — file handling, chat modes, timeouts, and more.

OpenClaw (fire-and-forget):

python

result = client.create_chat(
    prompt="[your task prompt]",
    notify_session_key="agent:main:main",
    task_label="my-task",
    chat_mode="agent",
)

All agents except OpenClaw (blocks until done):

python

from cellcog import CellCogClient
client = CellCogClient(agent_provider="openclaw|cursor|claude-code|codex|...")
result = client.create_chat(
    prompt="[your task prompt]",
    task_label="my-task",
    chat_mode="agent",
)
print(result["message"])

Choosing Mode & Tier

Use chat_mode="agent" (defaults to the "flash" tier) — project/document management operations are light tasks; flash is fast and economical. Pass chat_tier="max" only when a chat will ALSO do heavy work (deep analysis over the project's documents, complex production). Agent Team (chat_mode="team") is reserved for deep research.

Quick Start

python

from cellcog import CellCogClient

client = CellCogClient(agent_provider="openclaw")

# 1. Create a project
project = client.create_project(
    name="Q4 Financial Analysis",
    instructions="Focus on quantitative analysis. Use conservative estimates."
)
project_id = project["id"]
ct_id = project["context_tree_id"]

# 2. Upload documents
client.upload_document(ct_id, "/data/earnings_report.pdf", "Q4 2025 earnings report")
client.upload_document(ct_id, "/data/market_analysis.xlsx", "Competitor market share data")

# 3. Wait for processing (poll until all documents are ready)
import time
while True:
    docs = client.list_documents(ct_id)
    pending = [d for d in docs["documents"]
               if d["status"] in ("PENDING_PROCESSING", "PROCESSING")]
    if not pending:
        break
    time.sleep(10)

# 4. Read the context tree — structured summary of all documents
tree = client.get_context_tree_markdown(ct_id)
print(tree["markdown"])

# 5. Use with CellCog chat

# OpenClaw agents (fire-and-forget):
result = client.create_chat(
    prompt="Based on our project documents, create a board presentation",
    project_id=project_id,
    notify_session_key="agent:main:main",  # OpenClaw only
    task_label="board-deck",
)

# All other agents (blocks until done):
result = client.create_chat(
    prompt="Based on our project documents, create a board presentation",
    project_id=project_id,
    task_label="board-deck",
)

Project Lifecycle

Creating Projects

python

project = client.create_project(
    name="My Research Project",
    instructions="Optional instructions for CellCog agents working in this project"
)
# Returns: {"id": "...", "name": "...", "context_tree_id": "...", "created_at": "..."}

The creator is automatically an admin. Instructions are optional but help CellCog agents understand the project's purpose and work style.

Listing Projects

python

projects = client.list_projects()
# Returns: {"projects": [{"id", "name", "is_admin", "context_tree_id", "files_count", "created_at"}, ...]}

Every project in the list includes its context_tree_id — no need to call get_project() separately just to get it.

Getting Project Details

python

project = client.get_project(project_id)
# Returns: {"id", "name", "project_instructions", "context_tree_id", "is_admin", "created_at", ...}

Use get_project() when you need project_instructions or other details not included in the list.

Updating Projects

python

client.update_project(project_id, name="New Name", instructions="Updated instructions")

Admin access required.

Deleting Projects

python

client.delete_project(project_id)

Admin access required. Soft delete — contact support@cellcog.ai to recover.

Document Management

All document operations use context_tree_id, not project_id. Get it from list_projects(), create_project(), or get_project() response.

Uploading Documents

python

result = client.upload_document(
    context_tree_id=ct_id,
    file_path="/path/to/document.pdf",
    brief_context="Q4 2025 earnings report with revenue breakdown"
)
# Returns: {"file_id": "...", "status": "processing", "message": "..."}

Admin access required. The project creator is automatically an admin.

brief_context matters. CellCog's AI uses it to generate better summaries in the context tree. A good brief context significantly improves the quality of the structured summary that agents will read later.

Supported file types: PDF, DOCX, XLSX, PPTX, CSV, TXT, MD, images (JPG/PNG/GIF/WebP/SVG), audio (MP3/WAV/AAC/FLAC), video (MP4/AVI/MOV), and code files (JS/PY/Java/Go/etc.).

Max file size: 100 MB per file.

Credit usage: Uploads are processed by a lightweight AI agent using credits, so agents can access structured summaries and decide which documents to pull into context. Credit cost varies by document size and complexity.

Processing time: After upload, CellCog processes the document (extracts text, generates summaries, updates the context tree). This takes 1-3 minutes for typical documents, longer for large files.

Waiting for Document Processing

After uploading, poll until processing completes:

python

import time
while True:
    docs = client.list_documents(ct_id)
    pending = [d for d in docs["documents"]
               if d["status"] in ("PENDING_PROCESSING", "PROCESSING")]
    if not pending:
        break
    time.sleep(10)

Listing Documents

python

docs = client.list_documents(ct_id)
# Returns: {"documents": [{"id", "original_filename", "file_type", "file_size", "status", ...}]}

Document status values:

PENDING_PROCESSING — Queued for processing
PROCESSING — Being processed
SUCCEEDED — Ready and in context tree
ERRORED — Processing failed (check processing_error)

Deleting Documents

python

client.delete_document(ct_id, file_id)

# Or bulk delete (up to 100 at once):
client.bulk_delete_documents(ct_id, [file_id_1, file_id_2, ...])

Admin access required.

Context Trees — Your Knowledge Structure

After documents are processed, CellCog organizes them into a Context Tree — a hierarchical markdown representation with file descriptions, metadata, and content summaries. This is the same proprietary data structure that CellCog's internal agents use.

Getting the Context Tree Markdown

python

# Default: compact view with short summaries
tree = client.get_context_tree_markdown(ct_id)
print(tree["markdown"])

# Detailed view: includes long descriptions for each document
tree = client.get_context_tree_markdown(ct_id, include_long_description=True)
print(tree["markdown"])

Use include_long_description=True when you need full document details for deeper analysis. Default short descriptions are sufficient for most use cases and keep context windows efficient.

Example output:

text

## 📁 / (Q4 Financial Analysis Documents)
Document repository for Q4 Financial Analysis.

### 📁 /financials (Financial Reports)
Core financial documents and earnings data

#### 📄 /financials/earnings_report.pdf (Q4 2025 Earnings Report)
*Created: 2 hours ago*
**Type:** PDF (2.1 MB)

Comprehensive Q4 2025 earnings report with revenue breakdown by segment,
operating margins, and forward guidance. Revenue grew 15% YoY to $12.3B.

### 📁 /market (Market Data)
Competitive landscape and market research

#### 📄 /market/market_analysis.xlsx (Competitor Market Share Data)
*Created: 2 hours ago*
**Type:** XLSX (450.5 KB)

Market share analysis across 5 competitors. Includes quarterly trends,
geographic breakdown, and pricing comparison matrix.

Why Context Trees Matter for Agents

Understand before downloading. Read the tree to know what's available without downloading every file.
AI-processed summaries. Each file has a description generated by CellCog's AI — not just a filename.
Hierarchical organization. Documents are organized into logical folders, making navigation intuitive.
Same view as CellCog agents. When you pass project_id to a CellCog chat, the agent sees this exact tree.

Signed URLs — Share Your Documents

Generate time-limited, pre-authenticated download URLs for any documents in the context tree. These URLs work without CellCog authentication — pass them to other agents, tools, or humans.

By File Path (Recommended)

Use paths directly from the context tree markdown — no file IDs needed:

python

urls = client.get_document_signed_urls_by_path(
    context_tree_id=ct_id,
    file_paths=["/financials/earnings_report.pdf", "/market/analysis.xlsx"],
    expiration_hours=24  # Valid for 24 hours (default: 1 hour, max: 168 = 7 days)
)

# Returns:
# {
#     "urls": {"/financials/earnings_report.pdf": "https://storage.googleapis.com/...", ...},
#     "errors": {}
# }

By File ID (Alternative)

Use file IDs from list_documents():

python

urls = client.get_document_signed_urls(
    context_tree_id=ct_id,
    file_ids=["file_id_1", "file_id_2"],
    expiration_hours=24
)

Use Cases

Cross-agent sharing. Pass URLs to other agents that need to read your documents.
Human sharing. Send URLs to your human so they can download files directly.
External tool integration. Pass URLs to APIs that accept file URLs (e.g., analysis services).
Temporary access. Use short expiry (1 hour) for one-time access, long expiry (7 days) for ongoing workflows.

Note: Signed URLs remain valid for their full duration even if the user's project access is later revoked. New URLs cannot be generated after access is removed.

Using Projects with CellCog Chats

Projects are first-class in CellCog. When you pass a project_id, CellCog agents automatically get:

All project documents via the context tree
Project instructions that guide agent behavior
Organization context if the project belongs to an organization

Quick start:

python

result = client.create_chat(
    prompt="[your task prompt]",
    task_label="my-task",
    chat_mode="agent",  # See cellcog skill for all modes
)

See https://cellcog.ai for complete SDK API reference — delivery modes, send_message(), timeouts, file handling, and more.

Finding project and role IDs:

python

# List all projects
projects = client.list_projects()

# Get project details (includes context_tree_id)
project = client.get_project(project_id)

# List agent roles in a project
roles = client.list_agent_roles(project_id)

API Reference