Den Den

Agent-to-orchestrator communication layer. A gRPC transport where agents call back to the orchestrator via the denden CLI.

Orchestrator (Python gRPC server)
  ├── spawns agents as subprocesses
  └── handles ask_user / delegate / remember / recall requests
         ▲
         │ gRPC (localhost)
         │
     denden CLI (Go binary)
       └── called by agents to send requests

Components

Quick start

Install the server

cd server
pip install -e '.[dev]'

Build the CLI

cd cli
go build -o denden .

Run the server

denden-server --verbose

Use the CLI

# Health check
./cli/denden status

# Ask user a question
./cli/denden send '{
  "askUser": {
    "question": "Which language?",
    "choices": ["Python", "Go", "Rust"]
  }
}'

# Delegate to a sub-agent
./cli/denden send '{
  "delegate": {
    "delegateTo": "implementer",
    "task": {
      "text": "implement auth module",
      "returnFormat": "TEXT"
    }
  }
}'

# Remember information
./cli/denden send '{
  "remember": {
    "content": "This project uses pytest",
    "keywords": ["testing", "pytest"],
    "scope": "project"
  }
}'

# Recall stored information
./cli/denden send '{
  "recall": {
    "query": "testing framework",
    "scope": "project",
    "maxResults": 5
  }
}'

The CLI auto-fills request_id, denden_version, trace.created_at, and trace fields from environment variables.

Environment variables

Protocol

Single .proto file at proto/denden.proto. Two RPCs:

• Send — dispatches ask_user, delegate, remember, or recall requests (oneof payload)
• Status — health check

Response statuses: OK, DENIED, ERROR.

Regenerate stubs

make proto

Requires protoc, protoc-gen-go, protoc-gen-go-grpc, and grpcio-tools.

Server as a library

from denden import DenDenServer, ok_response
from denden.gen import denden_pb2

server = DenDenServer(addr="127.0.0.1:9700")

def handle_ask_user(request):
    answer = input(request.ask_user.question + " ")
    return ok_response(
        request.request_id,
        ask_user_result=denden_pb2.AskUserResult(text=answer),
    )

def handle_delegate(request):
    # ... run the delegated task ...
    return ok_response(
        request.request_id,
        delegate_result=denden_pb2.DelegateResult(text="done"),
    )

server.on_ask_user(handle_ask_user)
server.on_delegate(handle_delegate)
server.on_remember(handle_remember)
server.on_recall(handle_recall)
server.run()

Dynamic modules

The server CLI supports loading modules at startup:

denden-server --load-module my_custom_module

Modules must expose a module attribute or create_module() function returning a denden.Module subclass.