cleveragents-core/docs/showcase/cli-tools/project-init-and-context-management.md

Project Init & Context Management: Setting Up Your First CleverAgents Workspace

Overview

This example demonstrates how to initialize a CleverAgents project, manage namespaced projects, add files to context, and work with interactive sessions — all from the command line. You'll learn the complete project lifecycle from init through project create, project list, project show, and context management.

Prerequisites

• CleverAgents installed (pip install cleveragents)
• Python 3.12 or higher

What You'll Build

A fully initialized CleverAgents workspace with:

• A project directory with .cleveragents/ data store (SQLite database, config, and directory structure)
• One or more named projects in the local/ namespace
• Files added to the active context for AI-assisted work
• An interactive session ready for actor-driven tasks

---

Step-by-Step Walkthrough

Step 1: Initialize a New Project

Create a fresh directory and initialize CleverAgents inside it:

$ mkdir my-workspace && cd my-workspace
$ python -m cleveragents project init my-workspace --yes

Expected Output:

╭──────────────────────────────────────────────────────────────╮
│ Data Dir: /path/to/my-workspace/.cleveragents (created)      │
│ Config: /path/to/my-workspace/.cleveragents/config.toml      │
│ Database: initialized (schema v3)                            │
│ Directories: logs, cache, sessions, contexts                 │
╰──────────────────────────────────────────────────────────────╯
✓ OK Initialized (non-interactive)

What's Happening: CleverAgents creates a .cleveragents/ directory inside your workspace with a SQLite database (schema v3), a TOML configuration file, and four subdirectories: logs/, cache/, sessions/, and contexts/. The --yes flag skips interactive prompts, making it ideal for scripting and CI/CD pipelines.

---

Step 2: Create a Named Project

Projects in CleverAgents use a namespace/name format. The local/ namespace is the default for user-created projects:

$ python -m cleveragents project create local/my-webapp --description "A sample web application project"

Expected Output:

╭─────────────────────────────────────────────╮
│ ✓ Project 'local/my-webapp' created.        │
│ Namespace: local                            │
│ Description: A sample web application project│
│ Resources: 0                                │
╰─────────────────────────────────────────────╯

What's Happening: The project is registered in the CleverAgents database with a unique namespaced identifier (local/my-webapp). Projects can later be linked to resources (git repositories, file systems, APIs) to give actors access to your codebase.

---

Step 3: List All Projects

View all registered projects in a formatted table:

$ python -m cleveragents project list

Expected Output:

                                    Projects                                    
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Name               ┃ Namespace ┃ Description                  ┃ Resources ┃ Created    ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ local/my-webapp    │ local     │ A sample web application...  │         0 │ 2026-04-07 │
└────────────────────┴───────────┴──────────────────────────────┴───────────┴────────────┘

What's Happening: The table shows all projects with their namespaced name, namespace, description, linked resource count, and creation date. You can filter by namespace with --namespace local or use a regex pattern as an argument.

---

Step 4: Get Machine-Readable JSON Output

For scripting and automation, use --format json:

$ python -m cleveragents project list --format json

Expected Output:

{
  "command": "",
  "status": "ok",
  "exit_code": 0,
  "data": [
    {
      "namespaced_name": "local/my-webapp",
      "namespace": "local",
      "name": "my-webapp",
      "description": "A sample web application project",
      "linked_resources": [],
      "created_at": "2026-04-07T09:05:47.397876+00:00",
      "updated_at": "2026-04-07T09:05:47.397878+00:00"
    }
  ],
  "timing": {
    "duration_ms": 0
  },
  "messages": [
    {
      "level": "ok",
      "text": "ok"
    }
  ]
}

What's Happening: All CleverAgents commands support --format json, --format yaml, and --format plain for machine-readable output. The JSON envelope includes status, exit_code, data, timing, and messages fields — perfect for parsing in shell scripts or CI pipelines.

---

Step 5: Show Project Details

Inspect a specific project's full details:

$ python -m cleveragents project show local/my-webapp

Expected Output:

╭──────────── Project: local/my-webapp ─────────────╮
│ Name: local/my-webapp                             │
│ Namespace: local                                  │
│ Description: A sample web application project     │
│ Created: 2026-04-07 09:05:47.397876+00:00         │
│ Updated: 2026-04-07 09:05:47.397878+00:00         │
│                                                   │
│ Linked Resources: (none)                          │
╰───────────────────────────────────────────────────╯

What's Happening: project show displays the full project record including timestamps and any linked resources. Once you link a git repository or filesystem resource, it will appear in the "Linked Resources" section.

---

Step 6: Check Project Status

View the current project's operational status (run from inside the initialized directory):

$ python -m cleveragents project status

Expected Output:

╭──────────── Project Status ────────────╮
│ Project: my-workspace                  │
│ Path: /path/to/my-workspace            │
│ Created: 2026-04-07 09:08:58.334990    │
│                                        │
│ Statistics:                            │
│   Plans: 1                             │
│   Context Files: 0                     │
│   Total Changes: 0                     │
│   Current Plan: main                   │
╰────────────────────────────────────────╯

What's Happening: project status reads the .cleveragents/ directory in the current working directory and shows the active project's statistics — number of plans, context files, total changes, and the current plan name.

---

Step 7: Add Files to Context

Add source files to the active context so actors can work with them:

$ python -m cleveragents actor context add src/main.py

Expected Output:

✓ Added 1 file(s) to context:
  • /path/to/my-workspace/src/main.py

What's Happening: Files added to context are stored in the project's .cleveragents/ database and made available to actors during plan execution. You can add individual files, directories (recursively), or use glob patterns.

---

Step 8: List Context Files

View all files currently in context:

$ python -m cleveragents actor context list

Expected Output:

                  Context Files (1 total)                   
┏━━━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ File Path      ┃ Type ┃ Size     ┃ Added                      ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ src/main.py    │ file │ 48 bytes │ 2026-04-07 09:08:15.720873 │
└────────────────┴──────┴──────────┴────────────────────────────┘

What's Happening: The context list shows each file's relative path, type (file or directory), size, and when it was added. This is the set of files that actors will have access to when executing plans.

---

Step 9: View File Content in Context

Inspect the content of a specific context file:

$ python -m cleveragents actor context show src/main.py

Expected Output:

╭─ Content: /path/to/my-workspace/src/main.py ─╮
│ # Hello World                               │
│ print('Hello from CleverAgents!')           │
╰─────────────────────────────────────────────╯

What's Happening: actor context show renders the file content in a Rich panel. This is useful for verifying that the right content is in context before running an actor.

---

Step 10: Create an Interactive Session

Start a new interactive session for actor-driven conversations:

$ python -m cleveragents session create

Expected Output:

╭─────────────── Session ────────────────╮
│ Session ID: 01KNKK4Q9GZ0TRR5B0NEJYGMWH │
│ Actor: (none)                          │
│ Namespace: local                       │
│ Created: 2026-04-07 09:07              │
╰────────────────────────────────────────╯
╭────── Settings ───────╮
│ Automation: default   │
│ Streaming: off        │
│ Context: default      │
│ Memory: enabled       │
│ Max History: 50 turns │
╰───────────────────────╯
✓ OK Session created

What's Happening: Sessions are persistent conversation threads that can be bound to an actor (e.g., --actor openai/gpt-4). Each session gets a unique ULID identifier. Sessions store conversation history and can be resumed later.

---

Step 11: List Sessions

View all active sessions:

$ python -m cleveragents session list

Expected Output:

                           Sessions                            
┏━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
┃ ID       ┃ Name      ┃ Actor  ┃ Messages ┃ Updated          ┃
┡━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
│ 01KNKK4Q9GZ0TRR5B0NEJYGMWH │ (unnamed) │ (none) │        0 │ 2026-04-07 09:07 │
└──────────┴───────────┴────────┴──────────┴──────────────────┘

╭────────────────────────────────── Summary ───────────────────────────────────╮
│ Total:          1                                                            │
│ Most Recent:    01KNKK4Q9GZ0TRR5B0NEJYGMWH                                                     │
│ Oldest:         01KNKK4Q9GZ0TRR5B0NEJYGMWH                                                     │
│ Total Messages: 0                                                            │
│ Storage:        0 KB                                                         │
╰──────────────────────────────────────────────────────────────────────────────╯

✓ OK 1 sessions listed

What's Happening: The session list shows all sessions with their full ULID, optional name, bound actor, message count, and last update time. The summary panel provides aggregate statistics across all sessions.

---

Step 12: Get Session List as JSON

$ python -m cleveragents session list --format json

Expected Output:

{
  "command": "",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "sessions": [
      {
        "id": "01KNKK4Q9GZ0TRR5B0NEJYGMWH",
        "name": null,
        "actor": "(none)",
        "messages": 0,
        "updated": "2026-04-07T09:07:27.152323"
      }
    ],
    "summary": {
      "total": 1,
      "most_recent": "01KNKK4Q9GZ0TRR5B0NEJYGMWH",
      "oldest": "01KNKK4Q9GZ0TRR5B0NEJYGMWH",
      "total_messages": 0,
      "storage": "0 KB"
    }
  },
  "timing": {
    "duration_ms": 0
  },
  "messages": [
    {
      "level": "ok",
      "text": "ok"
    }
  ]
}

---

Step 13: Clean Up — Remove Context and Delete Project

Remove files from context when done:

$ python -m cleveragents actor context remove src/main.py

Expected Output:

✓ Removed 1 file(s) from context.

Delete a project when no longer needed:

$ python -m cleveragents project delete --yes local/my-webapp

Expected Output:

✓ Project 'local/my-webapp' deleted.

---

Complete Interaction Log

Click to see the full verified command sequence

# 1. Initialize workspace
$ mkdir my-workspace && cd my-workspace
$ python -m cleveragents project init my-workspace --yes
╭──────────────────────────────────────────────────────────────╮
│ Data Dir: /path/to/my-workspace/.cleveragents (created)      │
│ Config: /path/to/my-workspace/.cleveragents/config.toml      │
│ Database: initialized (schema v3)                            │
│ Directories: logs, cache, sessions, contexts                 │
╰──────────────────────────────────────────────────────────────╯
✓ OK Initialized (non-interactive)

# 2. Create a project
$ python -m cleveragents project create local/my-webapp --description "A sample web application project"
╭─────────────────────────────────────────────╮
│ ✓ Project 'local/my-webapp' created.        │
│ Namespace: local                            │
│ Description: A sample web application project│
│ Resources: 0                                │
╰─────────────────────────────────────────────╯

# 3. List projects
$ python -m cleveragents project list
                                    Projects                                    
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Name               ┃ Namespace ┃ Description                  ┃ Resources ┃ Created    ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ local/my-webapp    │ local     │ A sample web application...  │         0 │ 2026-04-07 │
└────────────────────┴───────────┴──────────────────────────────┴───────────┴────────────┘

# 4. Show project details
$ python -m cleveragents project show local/my-webapp
╭──────────── Project: local/my-webapp ─────────────╮
│ Name: local/my-webapp                             │
│ Namespace: local                                  │
│ Description: A sample web application project     │
│ Created: 2026-04-07 09:05:47.397876+00:00         │
│ Updated: 2026-04-07 09:05:47.397878+00:00         │
│                                                   │
│ Linked Resources: (none)                          │
╰───────────────────────────────────────────────────╯

# 5. Add file to context
$ python -m cleveragents actor context add src/main.py
✓ Added 1 file(s) to context:
  • /path/to/my-workspace/src/main.py

# 6. List context
$ python -m cleveragents actor context list
                  Context Files (1 total)                   
┏━━━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ File Path      ┃ Type ┃ Size     ┃ Added                      ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ src/main.py    │ file │ 48 bytes │ 2026-04-07 09:08:15.720873 │
└────────────────┴──────┴──────────┴────────────────────────────┘

# 7. Create a session
$ python -m cleveragents session create
╭─────────────── Session ────────────────╮
│ Session ID: 01KNKK4Q9GZ0TRR5B0NEJYGMWH │
│ Actor: (none)                          │
│ Namespace: local                       │
│ Created: 2026-04-07 09:07              │
╰────────────────────────────────────────╯
╭────── Settings ───────╮
│ Automation: default   │
│ Streaming: off        │
│ Context: default      │
│ Memory: enabled       │
│ Max History: 50 turns │
╰───────────────────────╯
✓ OK Session created

# 8. List sessions
$ python -m cleveragents session list
                           Sessions                            
┏━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
┃ ID       ┃ Name      ┃ Actor  ┃ Messages ┃ Updated          ┃
┡━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
│ 01KNKK4Q9GZ0TRR5B0NEJYGMWH │ (unnamed) │ (none) │        0 │ 2026-04-07 09:07 │
└──────────┴───────────┴────────┴──────────┴──────────────────┘
✓ OK 1 sessions listed

---

Key Takeaways

• project init --yes creates the .cleveragents/ data directory with SQLite database, config, and subdirectories — use --yes for non-interactive/CI usage.
• Namespaced projects (local/name) are the primary unit of organization. The local/ namespace is for user-created projects; other namespaces are used for remote/shared projects.
• All commands support --format json (and yaml, plain) for machine-readable output — ideal for scripting and automation pipelines.
• Context management (actor context add/list/show/remove) controls which files actors can access during plan execution.
• Sessions are persistent conversation threads with unique ULID identifiers, configurable automation settings, and optional actor bindings.
• project list supports --namespace filtering and regex pattern matching for large project registries.

---

Try It Yourself

Now that you've seen the full project lifecycle, try these variations:

• Create multiple projects and use project list --namespace local to filter them
• Filter with regex: project list ".*webapp.*" to find projects matching a pattern
• Add a whole directory: actor context add src/ to recursively add all files in a directory
• Bind a session to an actor: session create --actor openai/gpt-4 to start an AI-powered session
• Export project data: project list --format yaml > projects.yaml to save project state
• Challenge: Create a project, add context files, create a session, then use session list --format json to parse the session ID programmatically

---

Related Examples

• CleverAgents CLI Basics — Core CLI patterns and help system
• Output Format Flags — Deep dive into --format json/yaml/plain/table
• Action & Plan Management — Using projects with plans and actions
• Resource & Skill Management — Linking resources to projects

---

This example was automatically generated and verified by the CleverAgents UAT system. Feature area: Project init and context management | Test cycle: 1 | Generated: 2026-04-07

---

Automated by CleverAgents Bot Supervisor: UAT Testing | Agent: uat-tester