Metadata-Version: 2.4
Name: taiji-cli
Version: 0.6.23
Summary: A unified experience for AI in your terminal.
License-File: LICENSE
Requires-Python: >=3.14
Requires-Dist: aiosqlite==0.22.1
Requires-Dist: bashlex==0.18
Requires-Dist: click==8.4.0
Requires-Dist: format-currency>=0.0.10
Requires-Dist: httpx==0.28.1
Requires-Dist: notify-py==0.3.43
Requires-Dist: packaging==26.2
Requires-Dist: pathspec==1.1.1
Requires-Dist: platformdirs==4.9.6
Requires-Dist: psutil==7.2.2
Requires-Dist: pyperclip==1.11.0
Requires-Dist: rich==15.0.0
Requires-Dist: setproctitle==1.3.7
Requires-Dist: textual-diff-view==0.1.5
Requires-Dist: textual-serve>=1.1.2
Requires-Dist: textual-speedups==0.2.1
Requires-Dist: textual[syntax]==8.2.7
Requires-Dist: typeguard==4.5.2
Requires-Dist: typing-extensions==4.15.0
Requires-Dist: watchdog==6.0.0
Requires-Dist: xdg-base-dirs>=6.0.2
Description-Content-Type: text/markdown

# Taiji

A unified interface for AI in your terminal ([release announcement](https://willmcgugan.github.io/toad-released/)).

<table>

  <tbody>

  <tr>
    <td><img alt="Screenshot 2026-01-30 at 19 23 54" src="https://github.com/user-attachments/assets/aca51988-359a-466d-bdd1-050dc3d678ac" /></td> 
    <td><img alt="Screenshot 2026-01-30 at 19 21 00" src="https://github.com/user-attachments/assets/b9b0a6bb-e084-4976-86c2-cccdb42041ae" /></td>    
  </tr>

  <tr>
    <td><img alt="Screenshot 2026-01-30 at 19 29 47" src="https://github.com/user-attachments/assets/3fe4060f-d468-4635-b80f-03c24625c6c0" /></td>
    <td><img alt="Screenshot 2026-01-30 at 19 30 08" src="https://github.com/user-attachments/assets/03659d64-02fc-4936-a90d-e202bc4b70a1" /></td>
  </tr>
    
  </tbody>
  
</table>

## Quickstart

Install from PyPI:

```bash
pip install taiji-cli
```

Or install the standalone command with UV:

```bash
uv tool install taiji-cli
```

Run:

```
taiji
```

See [Getting Started](#getting-started) if you have any problems.

## What is Taiji?

Taiji is an interface to coding agents, such as Claude, Gemini, Codex, OpenHand, and many more.

Taiji blends a traditional shell based workflow and powerful agentic AI, with an intuitive Terminal User Interface.

<table>
  <tbody>
    <tr>
      <td>
        <h3>AI "App store"</h3>
        <p>
        Find, install, and run dozens of agents directly from the Taiji UI.
        <p>
        There is a large and growing list of AI agents that work with Taiji.
        Discover agents from big tech and smaller Open Source projects.
        <p>
        Developers can add support for their own agents, via the <a href="https://agentclientprotocol.com/overview/introduction">Agent Client Protocol</a>.
      </td>
      <td>
        <img alt="Screenshot 2026-01-27 at 12 48 30" src="https://github.com/user-attachments/assets/f7bd3776-6405-47e5-9d1f-11a12a4ce3b2" />
      </td>
    </tr>
    <tr>
      <td>
      <h3>Taiji Shell</h3>
      <p>
      While most terminal agent interfaces can run commands (with the <kbd>!</kbd> syntax), they aren't running a shell.
      If you change directory or set environment variables, they won't persist from one command to the next.
      <p>
      Output that contains more than simple text will typically be garbled, and anything interactive will fail or even break the TUI entirely.
      <p>
      Taiji integrates a fully working shell with full-color output, interactive commands, and tab completion.
      Allowing you to interleave prompts for the agent with terminal workflows.
      <p>
      At time of writing Taiji is the only terminal UI which does this.
      </td>
      <td><img src="https://github.com/user-attachments/assets/ac9247bb-3daa-4bb7-b3fd-e0bbd22475fa"/></td>        
    </tr>
    <tr>
      <td>
        <h3>Prompt Editor</h3>
        <p>
        Taiji has a nice Markdown prompt editor, with syntax highlighting for code fences.
        Full mouse support, cut and paste, many keybindings and shortcuts.
      </td>
      <td>
        <img src="https://github.com/user-attachments/assets/3d619b94-ec53-4e7a-b905-5aef6f4fa8a6"/>
      </td>
    </tr>
    <tr>
      <td>
        <h3>File Picker</h3>
        <p>
        Add a file to your prompt with <kbd>@</kbd>, and Taiji will show a fuzzy file picker.
        <p>
        Type a few characters from the filename or folder and Taiji will refine the search as you type.
        Hit <kbd>enter</kbd> to add the file to the prompt.
        <p>
        The fuzzy picker is great when you know the file you want to mention.
        If you want to explore your files, you can press <kbd>tab</kbd> to switch to an interactive tree control.                
      </td>
      <td>
        <img src="https://github.com/user-attachments/assets/ab25c389-1d2f-4006-a1d8-159edbd3ed00"/>        
      </td>
    </tr>
    <tr>
      <td>
        <h3>Beautiful Diffs</h3>
        <p>
        Side-by-side or unified diffs, with syntax highlighting for most languages.      
      </td>
      <td>
        <img alt="Screenshot 2026-01-27 at 12 44 22" src="https://github.com/user-attachments/assets/b3d6c29c-d6ec-4253-a9dc-2df0ff21e293" />
      </td>      
    </tr>
    <tr>
      <td>
        <h3>Elegant Markdown</h3>
        <p>
        Markdown is the language of LLMs (AI).
        Taiji's streaming Markdown support can display syntax highlighted code fences, elegant tables, quotes, lists, and more.
      </td>
      <td>
        <img src="https://github.com/user-attachments/assets/b650b407-f4ab-4cb9-8920-55c15073598e"/>
      </td>
    </tr>
    <tr>
      <td>
        <h3>Simple Settings</h3>
        <p>
        An intuitive settings system (no need to manually edit JSON files).
        <p>
        Tune Taiji to your liking.
        Almost everything in Taiji may be tweaked.
        If you want to create an ultra-minimal UI with nothing more than a prompt—you can!                
      </td>
      <td>
        <img src="https://github.com/user-attachments/assets/2ff0de12-c2e1-455b-954a-21e66c070dd8"/>      
      </td>    
    </tr>
    <tr>
      <td>
        <h3>Concurrent sessions</h3>
        <p>
        Launch and run multiple agents from potentially different providers.
        <p>
        Hit <kbd>ctrl+s</kbd> to show the current state of all your agents in one screen.
        </p>        
      </td> 
      <td>
        <img  alt="Screenshot 2026-02-16 at 17 33 40-fs8" src="https://github.com/user-attachments/assets/cd3128eb-b348-4f40-b5c0-4816d07dcbe9" />
      </td>    
    </tr>
    <tr>
      <td>
        <h3>Session Resume</h3>
        <p>
        Resume previous sessions with your agent.    
        <p>
        Hit <kbd>ctrl+r</kbd> to pick a previous session to resume.
      </td>
      <td>
        <img alt="Screenshot 2026-02-01 at 16 57 46" src="https://github.com/user-attachments/assets/7c1ad59e-027c-4542-a216-9a32ef573936" />
      </td>    
    </tr>    
  </tbody>
</table>

## Video

Watch a preview of the Taiji User Interface:

https://github.com/user-attachments/assets/ced36f4b-db02-4d29-8a0a-14ec64b22881


## Compatibility

Taiji runs on Linux and macOS. Native Windows support is currently lacking (but on the roadmap), but Taiji will run quite well with WSL.

Taiji is a terminal application.
Any terminal will work, although if you are using the default terminal on macOS you will get a much reduced experience.
I recommend [Ghostty](https://ghostty.org/) which is fully featured and has amazing performance.

### Clipboard

On Linux, you may need to install `xclip` to enable clipboard support.

```
sudo apt install xclip
```

## Getting Started

The easiest way to install Taiji is with the published `taiji-cli` package:

```bash
pip install taiji-cli
```

You should now have `taiji` installed.

If that doesn't work for any reason, then you can install with the following steps:

First [install UV](https://docs.astral.sh/uv/getting-started/installation/):

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Then use UV to install Taiji:

```bash
uv tool install -U taiji-cli --python 3.14
```

Taiji is also available on [conda-forge](https://conda-forge.org), and can be installed using [pixi](https://pixi.prefix.dev/latest/#installation):

```bash
pixi global install taiji-cli
```

## Using Taiji

Launch Taiji with the following:

```bash
taiji
```

When no agent is specified, Taiji checks for Claude, Codex, and Gemini in that
order and automatically starts the first two available ACP agents. If none are
installed, it opens the agent store as usual.

You should see something like this:

<img alt="front-fs8" src="https://github.com/user-attachments/assets/8831f7de-5349-4b3f-9de9-d4565b513108" />

From this screen you will be able to find, install, and launch a coding agent.
If you already have an agent installed, you can skip the install step.
To launch an agent, select it and press <kbd>space</kbd>.

The footer will always display the most significant keys for the current context.
To see all the keys, press <kbd>F1</kbd> to display the help panel.

### Taiji CLI

When running Taiji, the current working directory is assumed to be your project directory.
To use another project directory, add the path to the command.
For example:

```bash
taiji ~/projects/my-awesome-app
```

If you want to skip the initial agent screen, add the `-a` switch with the name of your chosen agent.
For example:

```bash
taiji -a open-hands
```

### Two-agent relay

Run two ACP agents together:

```bash
taiji run -a claude --agent2 codex PATH
```

Use `--max-rounds 12` to raise the automated relay limit for a larger task;
the default is 100 turns.

Use `Ctrl+C`, `Ctrl+Shift+P`, or `/taiji:pause` to pause and resume all agents. While
paused, new messages remain queued. To bypass alternation and address one
agent directly, use a tag such as `@claude: inspect the failing test`.

To see all subcommands and switches, add the `--help` switch:

```bash
taiji --help
```

### Web server

You can run Taiji as a web application.

Run the following, and click the link in the terminal:

```bash
taiji serve
```

![textual-serve](https://github.com/user-attachments/assets/1d861d48-d30b-44cd-972d-5986a01360bf)

## Taiji development

Taiji was built by [Will McGugan](https://github.com/willmcgugan) and is currently under active development.

To discuss Taiji, see the Discussions tab, or join the #toad channel on the [Textualize discord server](https://discord.gg/Enf6Z3qhVr).



### Roadmap

Some planned features:

- [ ] UI for MCP servers
- [ ] Expose model selection (waiting on ACP update)
- [x] Sessions (resume)
- [x] Multiple agents
- [ ] Windows native support
- [ ] Builtin editor
- [ ] Sidebar (widgets)
  - [ ] Git pending changes

### Reporting bugs

This project is trialling a non-traditional approach to issues.
Before an issue is created, there must be a post in Discussions, approved by a Taiji dev (Currently @willmcgugan).

By allowing the discussions to happen in the Discussion tabs, issues can be reserved for actionable tasks with a clear description and goal.


## Licensing

Taiji is licensed under the [AGPL](./LICENSE) license. Commercial licenses are available. See [COMMERCIAL_LICENSE.md](./COMMERCIAL_LICENSE.md).































