> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# praisonai-code package migration

> Where the agentic terminal CLI lives during the incremental C0–C6 extraction from the praisonai wrapper.

`praisonai-code` is a new sibling package that will host the agentic terminal CLI, extracted incrementally from the `praisonai` wrapper without breaking any existing install or import path.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(
    name="CLI Assistant",
    instructions="Answer prompts from the terminal CLI.",
)

agent.start("Say hello from praisonai run")
```

The user keeps using `pip install praisonai`; the extracted `praisonai-code` package powers the same CLI entry points.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    Agents[praisonaiagents<br/>SDK] --> Code[praisonai-code<br/>terminal CLI]
    Code --> Main[praisonai<br/>wrapper + shims]

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef config fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef success fill:#10B981,stroke:#7C90A0,color:#fff
    classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff

    class Agents agent
    class Code tool
    class Main config
```

## Quick Start

<Steps>
  <Step title="Nothing changes for users">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install praisonai
    praisonai "say hello"
    ```
  </Step>

  <Step title="Optional: install praisonai-code for development">
    From the [PraisonAI](https://github.com/MervinPraison/PraisonAI) monorepo root:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install -e src/praisonai-code
    python -c "import praisonai_code; print(praisonai_code.__version__)"
    ```
  </Step>
</Steps>

***

## How It Works

Dependency flow is one-way: **`praisonai` → `praisonai-code` → `praisonaiagents`**. The `praisonai-code` package never declares a dependency on `praisonai`, which avoids a PyPI cycle. Bot, gateway, and daemon code moved to `praisonai-bot` in C9.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant CLI as praisonai CLI
    participant Code as praisonai_code.cli
    participant Agent as praisonaiagents.Agent

    Note over User,Agent: Future state (after C5)
    User->>CLI: praisonai "say hello"
    CLI->>Code: delegate agentic terminal path
    Code->>Agent: run agent
    Agent-->>Code: response
    Code-->>CLI: output
    CLI-->>User: terminal result
```

| Layer        | Package           | Role                                                                                                                                                                                                                                      |
| ------------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SDK          | `praisonaiagents` | Agents, tools, memory, workflows                                                                                                                                                                                                          |
| Terminal CLI | `praisonai-code`  | `run --output actions`, warm runtime, CLI backends. Default `run "…"`, `chat`, `code` host their entry points here but are **wrapper-required** — see the [standalone-limits table](/docs/features/praisonai-code-cli#standalone-limits). |
| User install | `praisonai`       | `pip install praisonai`, PEP 562 shims (bots/gateway/daemon moved to `praisonai-bot` in C9)                                                                                                                                               |

***

## Where should I work?

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Start{Who are you?}
    Start -->|End user| User[pip install praisonai<br/>No change]
    Start -->|Contributor on runtime / cli_backends| C1[After C1: praisonai_code.runtime<br/>praisonai_code.cli_backends]
    Start -->|Contributor on bots / gateway / daemon| Main[Use praisonai-bot package<br/>praisonai_bot.bots / gateway / daemon]
    Start -->|Library using PraisonAI class| Shim[from praisonai.cli.main import PraisonAI<br/>Keeps working via PEP 562 shim after C5]

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef config fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef success fill:#10B981,stroke:#7C90A0,color:#fff

    class User success
    class C1 tool
    class Main agent
    class Shim config
```

***

## Roadmap

| Step   | Scope                                                                     | Files | Status                                                             |
| ------ | ------------------------------------------------------------------------- | ----: | ------------------------------------------------------------------ |
| **C0** | Scaffold (this PR)                                                        |     5 | ✅ [PR #2539](https://github.com/MervinPraison/PraisonAI/pull/2539) |
| C1     | `runtime/` + `cli_backends/`                                              |     8 | ⏳                                                                  |
| C2     | `interactive/`, `execution/`, `ui/`, `output/`, `state/`                  |    30 | ⏳                                                                  |
| C3     | 80 agentic commands (9 bot-channel commands stay in main)                 |    80 | ⏳                                                                  |
| C4     | 158 agentic features (5 bot-channel features stay in main)                |   158 | ⏳                                                                  |
| C5     | `main.py`, `app.py`, config/session/utils + PEP 562 shims                 |    26 | ⏳                                                                  |
| C6     | Integration gate (smoke tests, import graph assertions, real agentic run) |     — | ⏳                                                                  |

Tracking issue: [PraisonAI#2512](https://github.com/MervinPraison/PraisonAI/issues/2512).

***

## Compatibility guarantees

<Note>
  **C7.1 (2026-07-02, PR #2559):** Package boundaries are now formally documented in-repo, and the `_wrapper_bridge` pattern is enforced by CI (`scripts/check_c7_imports.sh`, baseline 225 direct wrapper import lines). The regression gate blocks any new module-level wrapper imports outside the sanctioned allowlist. Standalone `praisonai-code` installs degrade gracefully for wrapper-only features rather than raising.
</Note>

* **`pip install praisonai` remains the only user-facing install.** `praisonai-code` is not published to PyPI standalone during migration.
* **Existing import paths keep working** — PEP 562 shims at old `praisonai.*` paths land as code moves in C1–C5. `from praisonai.cli.main import PraisonAI` continues unchanged (154+ tests depend on it).
* **Console entry unchanged** — `praisonai = "praisonai.__main__:main"`.
* **One-way dependencies** — `praisonai` → `praisonai-code` → `praisonaiagents`; `praisonai-code` never depends on `praisonai`.
* **Scope split** — `praisonai-code` covers only the agentic terminal product; `bots/`, `gateway/`, and `daemon/` moved to `praisonai-bot` in C9 (see [praisonai-bot Migration](/docs/guides/praisonai-bot-migration)). Although `praisonai-code` hosts the `chat`, `code`, and default `run` entry points, those commands are **wrapper-required** on a standalone install and emit an install hint (`pip install praisonai`).

***

## Best Practices

<AccordionGroup>
  <Accordion title="Do not import praisonai_code in library code (during migration)">
    Application and library code should keep using `import praisonai` and `from praisonaiagents import Agent`. Direct `praisonai_code` imports are for contributors working inside the monorepo until the public surface is explicitly documented after C5.
  </Accordion>

  <Accordion title="Bot-channel modules moved to praisonai-bot (C9)">
    As of C9, the following CLI commands and features live in `praisonai-bot`, not `praisonai-code`: `gateway`, `bot`, `onboard`, `pairing`, `identity`, `kanban`, `mint_link`, `claw`. The `praisonai.bots`, `praisonai.gateway`, and `praisonai.daemon` paths remain as `alias_package` shims. See [praisonai-bot Migration](/docs/guides/praisonai-bot-migration).
  </Accordion>

  <Accordion title="New agentic CLI features go into praisonai_code.cli.* (after C5)">
    Once C5 lands the layout, new terminal-agent commands and features belong under `praisonai_code.cli.*`, with shims left at the old `praisonai.cli.*` paths for compatibility.
  </Accordion>

  <Accordion title="PEP 562 shims are load-bearing">
    Removing shims would break 154+ tests and every `from praisonai.cli.main import PraisonAI` importer. Shim removal is tracked as a **5.0.0**-track breaking change on [issue #2512](https://github.com/MervinPraison/PraisonAI/issues/2512).
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Python wrapper" icon="box" href="/docs/developers/wrapper">
    Public `praisonai.run`, `PraisonAI`, and `praisonai.arun` surface
  </Card>

  <Card title="Development setup" icon="wrench" href="/docs/developers/development-setup">
    Clone the monorepo and install editable packages with uv
  </Card>

  <Card title="praisonai-bot Migration" icon="package" href="/docs/guides/praisonai-bot-migration">
    The sibling extraction that moves bots/gateway/daemon out of the wrapper
  </Card>
</CardGroup>