# 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:

```bash
$ 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:

```bash
$ 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:

```bash
$ 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`:

```bash
$ python -m cleveragents project list --format json
```

**Expected Output:**
```json
{
  "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:

```bash
$ 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):

```bash
$ 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:

```bash
$ 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:

```bash
$ 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:

```bash
$ 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:

```bash
$ 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:

```bash
$ 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

```bash
$ python -m cleveragents session list --format json
```

**Expected Output:**
```json
{
  "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:

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

**Expected Output:**
```
✓ Removed 1 file(s) from context.
```

Delete a project when no longer needed:

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

**Expected Output:**
```
✓ Project 'local/my-webapp' deleted.
```

---

## Complete Interaction Log

<details>
<summary>Click to see the full verified command sequence</summary>

```
# 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
```
</details>

---

## 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](cleveragents-cli-basics.md) — Core CLI patterns and help system
- [Output Format Flags](output-format-flags.md) — Deep dive into `--format json/yaml/plain/table`
- [Action & Plan Management](action-and-plan-management.md) — Using projects with plans and actions
- [Resource & Skill Management](resource-and-skill-management.md) — 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