Managing an army of agents: logs, oversight, ClickUp and CRM

Module: Professional practice | Time: about 30 min reading + 40 min practice

The gist

With one agent, everything is clear. With 10 or more, you lose track of who did what, how much it cost and why something went wrong yesterday.

🎨 Picture this: a restaurant with one cook vs. a restaurant with a crew of 15. You can keep an eye on one cook just by looking. A crew of 15 you can only manage through an order log, KPIs and shift schedules. Without them it's chaos: two cooks make the same dish, a third stands idle, and the head chef has no idea what's going on in the kitchen.

This lesson is about bringing order to your army of agents: audits, logs, status dashboards, and integration with ClickUp and a CRM.

Key concepts

• Why the "black box" is the root of every agent problem
• Three levels of logging: a file, a database, an external project management tool
• ClickUp MCP: the agent creates tasks and updates their status itself
• Notion as a knowledge base for agent results
• CRM integration: work finished, client record updated
• STATUS.md: a live dashboard Claude updates on its own

Theory

The "black box" problem

Without management, agents work like black boxes: you start them, they do something, they return a result. What happened inside? Which one started first? Why did one of them hang? How much money did they burn overnight?

🎨 Picture this: a taxi with no meter and no route. Did you get there? Great. How much did it cost? Unclear. Why were you late? A mystery. Can you repeat the exact same route? No.

Five symptoms of the "black box":

1. You don't know what a specific agent task cost
2. You can't reproduce a result because it's unclear what exactly the agent did
3. You don't know who started the agent and when
4. When there's an error, you can't tell at which step it happened
5. A client asks "what did your AI do?" and you have nothing to show

With management, the picture flips: a full audit trail, reproducibility, accountability and transparency for the client.

Three levels of logging

Agent logs come in three levels. Pick based on the job.

Start at level 1. Move up when you get a team or clients.

Level 1: A file log (agent-log.jsonl)

JSONL is a "one line = one record" format. It's handy: you can append to the end without rewriting the whole file, it's easy to parse, and grep works on it.

The amounts and dates in the examples below are made up.

{"ts":"2026-05-09T14:23:00Z","agent":"researcher","task":"market-analysis","status":"complete","output_tokens":2847,"cost_usd":0.08,"result_file":"reports/market-2026-05-09.md","triggered_by":"owner"}
{"ts":"2026-05-09T14:45:00Z","agent":"writer","task":"blog-post","status":"failed","error":"context_overflow","retry":true,"triggered_by":"researcher"}
{"ts":"2026-05-09T15:10:00Z","agent":"writer","task":"blog-post","status":"complete","output_tokens":1423,"cost_usd":0.04,"result_file":"posts/blog-2026-05-09.md","triggered_by":"retry-hook"}

What to put in each record:

ts            — timestamp in ISO 8601 (UTC)
agent         — who did the work
task          — what it did (a slug, not a sentence)
status        — pending / in_progress / complete / failed / skipped
output_tokens — how many tokens were in the agent's response
cost_usd      — what the request cost
result_file   — where the result is (path or URL)
triggered_by  — who started it (user / another agent / cron)
error         — the error, if status=failed
retry         — whether it needs another attempt

Instructions for the agent (in CLAUDE.md or the system prompt):

## Logging

After finishing ANY task, you MUST append a record to `agent-log.jsonl`.
Format: one line of JSON. Required fields: ts, agent, task, status.
Don't ask for permission. Do it automatically.

🎨 Picture this: a receipt after every purchase. The cashier doesn't ask "would you like a receipt printed?" It prints automatically. The agent doesn't ask "should I write this to the log?" It just writes it.

Level 2: A Supabase table

When a JSONL file isn't enough, for example when you need web access to the logs or several people check the status, move to Supabase.

Create the table:

create table agent_logs (
  id          uuid default gen_random_uuid() primary key,
  created_at  timestamptz default now(),
  agent       text not null,
  task        text not null,
  status      text not null check (status in ('pending','in_progress','complete','failed','skipped')),
  cost_usd    numeric(8,4),
  output_tokens integer,
  result_url  text,
  triggered_by text,
  error_msg   text,
  metadata    jsonb
);

The agent writes to it through the Supabase MCP:

# Connect the Supabase MCP
claude mcp add supabase -- npx -y @supabase/mcp-server-supabase \
  --access-token $SUPABASE_ACCESS_TOKEN
# Supabase's documentation also has a remote MCP server: check the current command there

Once it's connected, the agent says:

Write to the agent_logs table:
agent = "researcher"
task = "competitor-analysis"
status = "complete"
cost_usd = 0.12
result_url = "notion://pages/abc123"

Claude turns this into a SQL INSERT and runs it directly through the MCP.

Level 3: ClickUp MCP, the agent manages tasks

ClickUp is a project management tool. The agent can create tasks there, update their status and write comments. The client sees progress in real time, in a tool they already know.

Installing the ClickUp MCP:

# Option 1: through Composio (quick start). Composio's URL format has changed before, check its documentation
claude mcp add --transport http clickup-composio \
  https://mcp.composio.dev/clickup?apiKey=YOUR_COMPOSIO_KEY

# Option 2: the official ClickUp MCP (check its status and URL in ClickUp's documentation)
claude mcp add --transport http clickup \
  https://mcp.clickup.com/mcp

Once connected, the agent gets tools (the names depend on the server; these are examples):

• create_task: create a task
• update_task_status: change the status
• add_comment: add a comment
• get_tasks: get a list of tasks

Example workflow: a research agent finishes a market analysis.

The agent returned a report →
The agent created a ClickUp task "Market Analysis — Ecuador Real Estate 2026-05" →
Attached the result →
Set status = Done →
Created the next task "Write blog post based on research" →
You got a notification in ClickUp

Instructions for the agent:

## ClickUp integration

After finishing each task:
1. Update the task status in ClickUp to "Done" (use update_task_status)
2. Add a comment with a short summary (2-3 lines)
3. If there's a next step, create a new task
4. ClickUp lists: Research → List ID 901234, Writing → List ID 901235

🎨 Picture this: ClickUp is the task board in an office. A manager used to move the sticky notes around by hand. Now the agent moves the sticky notes itself, and the manager just looks at the board.

STATUS.md: a live dashboard

A STATUS.md file that Claude updates after every finished task:

# STATUS.md — AI Operations Dashboard

> Updated: 2026-05-09 15:47 UTC

## Active agents

| Agent | Task | Status | Cost | Updated |
|-------|--------|--------|-----------|-----------|
| researcher | market-analysis Ecuador | ✅ Done | $0.08 | 14:23 |
| writer | blog-post real estate | 🔄 In Progress | $0.04 | 15:10 |
| designer | thumbnail YouTube | ⏳ Queued | — | — |
| deployer | production deploy | ❌ Failed | $0.02 | 15:30 |

## Spent today

- Total: $0.14
- Agents started: 4
- Succeeded: 2 / Errors: 1 / In progress: 1

## Latest errors

- **deployer** 15:30 — context_overflow during deploy. Retry scheduled 16:00.

Add this to the agent's CLAUDE.md: "After each finished task, update STATUS.md: your own row plus the daily total."

Notion MCP: a knowledge base

ClickUp = for tasks and processes. Notion = for knowledge and results.

Each research agent writes a structured summary to Notion. Another agent reads it later and doesn't redo the same work.

# Notion's official remote MCP server (check the URL in Notion's documentation)
claude mcp add --transport http notion https://mcp.notion.com/mcp
# When you connect, Notion will ask you to sign in and grant access to the pages you need

Instructions for the agent:

## Notion: saving results

After each research task, create a page in the "Research" database:
- Title: [Topic] — [Date]
- Tags: research type, region, project
- Content: key findings (3-5 points), sources, confidence in the data
- A link to the full report

Before starting new research, search Notion first.
If similar work already exists, use it.

🎨 Picture this: a company wiki. When an employee leaves, the knowledge doesn't leave with them. When an agent's session "leaves," the knowledge stays in Notion.

An audit trail with Git hashes

The most reliable audit trail is Git commits.

{
  "ts": "2026-05-09T14:23:00Z",
  "agent": "researcher",
  "task": "competitor-analysis",
  "git_before": "abc123def",
  "git_after": "456789ghi",
  "files_changed": ["reports/competitors-2026-05-09.md"],
  "cost_usd": 0.08,
  "status": "complete",
  "duration_sec": 127
}

git diff abc123 456789 will show every line the agent changed. Full reproducibility.

CRM integration (HubSpot / Pipedrive)

The agent finishes an analysis for a client → a record appears in the CRM automatically.

# HubSpot through Composio (check the URL format in Composio's documentation)
claude mcp add --transport http hubspot \
  https://mcp.composio.dev/hubspot?apiKey=YOUR_KEY

Instructions for the agent:

## CRM update

If the task is tied to a client (there's a client_id):
1. Add a note in HubSpot: "[Agent] finished [task]. Result: [one line]"
2. Update the "Last AI Action" field with the date
3. If there's a next step for the account manager, create a task in the CRM

🎨 Picture this: a sales rep used to log into the CRM by hand after every call. Now the agent updates the CRM itself. The rep sees the current status without any manual work.

The maturity model: where to start

Step 1: agent-log.jsonl (15 min)
↓
Step 2: STATUS.md (30 min)
↓
Step 3: ClickUp MCP (2 hours)
↓
Step 4: Notion knowledge base (2-3 hours)
↓
Step 5: CRM integration (3-4 hours)
↓
Step 6: Supabase + a full audit trail (1 day)

Start with step 1 today.

Practice

1. Create agent-log.jsonl and add the instructions for the agent to CLAUDE.md
2. Create STATUS.md with an agents table
3. Run any agent and check that both files were updated
4. (Optional) Connect the ClickUp MCP if you have an account
5. (Optional) Connect the Notion MCP to save results

# Step 1
touch agent-log.jsonl

# Step 2
cat > STATUS.md << 'EOF'
# STATUS.md

> Updated: by hand

## Active agents

| Agent | Task | Status | Cost |
|-------|--------|--------|-----------|
| — | — | — | — |
EOF

# Step 3: check after the agent has worked
tail -5 agent-log.jsonl

Tools and resources

• ClickUp MCP: ClickUp's official server (check its status in the documentation)
• Composio: hundreds of integrations through one MCP
• Notion MCP: documentation for Notion's official MCP
• Supabase MCP: for databases
• HubSpot through Composio: CRM integration

Key takeaways

Agents without logs are black boxes. Start with agent-log.jsonl (15 minutes): one line of JSON after every task.

STATUS.md is a live dashboard the agent updates itself. You see the state of your whole army at a glance.

ClickUp MCP: the agent creates tasks and updates their status itself. The client sees progress in their own tool.

Notion is memory between sessions. You pay for a piece of research once, not every time over again.

Next lesson

→ Local AI models: Ollama, LM Studio and private AI