zaly

Hackable terminal coding agent.

zaly is an AI coding agent with a polished terminal UI, persistent sessions, flexible model support, explicit permissions, and a resource system built to be extended.

[!WARNING]

zaly is alpha software. It is already useful and fairly polished, but APIs,

configuration, session formats, and behavior may change before 1.0. Expect

rough edges.

✨ Features

• Fast by design — startup and session resume stay fast, even with very large

• A terminal UI built for agent work — use a focused fullscreen interface or

• Choose the right model per task — authenticate with multiple providers,

• Sessions that can keep going — sessions persist and resume per workspace.

• Built for both sides of the conversation — zaly keeps the agent aware of

• Tools without blocking the conversation — long-running tools become

• Explicit permissions — choose strict, readonly, permissive, or yolo,

• Hackable by design — add commands, reusable skills, resource packs, themes,

📋 Requirements

• Node.js 22.11 or newer
• Access to at least one supported model provider; credentials where required
• A modern terminal; mouse, clipboard, and terminal graphics support are

🚀 Install

With npm:

npm install -g @zaly/cli

Or with Bun:

bun add -g @zaly/cli

⚡ Quick start

cd your-project
zaly --yolo

Start typing to talk to the agent. zaly persists sessions and resumes the most recent session for the workspace unless you start a new one.

Useful first actions:

• /login authenticates with a model provider.
• /model browses and switches models.
• /help shows all available actions and keybindings.

🔐 Permissions

For now, we recommend the yolo preset for the smoothest experience with capable models. It allows every tool call without prompting, including shell commands and file writes. Only use it with models, tasks, and projects you trust.

Enable it for one invocation:

zaly --yolo

To make it persistent, run /config and add:

{
  "permissions": {
    "preset": "yolo"
  }
}

The other presets—strict, readonly, and permissive—provide progressively broader defaults and can be refined with explicit allow, ask, and deny rules.

⌨️ Essential actions

Type / in the composer to discover actions and commands. /help shows the complete list together with active keybindings.

| Action or key | What it does | | -------------------- | -------------------------------------------------------- | | /help, Ctrl-H | Show actions and keyboard shortcuts | | /login | Authenticate with a model provider | | /model | Browse or switch the model used for future turns | | /effort | Change the model's reasoning effort | | /context | Inspect the context currently sent to the model | | /tree | Browse the current session's message tree | | /new | Start a new session in the current workspace | | /resume | Find and resume another session | | /compact | Summarize older history while preserving recent messages | | /config | Edit user or project configuration | | /resources | Enable or disable resources for the workspace | | /plugins | Manage installed plugins | | /theme | Choose a color theme for the current session | | /stop, Esc | Stop the current agent turn or running tool batch | | Ctrl-Y | Copy the selection or composer input | | /history, Ctrl-R | Browse and reuse previous composer input |

🧩 Customization

zaly can load resources from both user and project configuration:

• Commands turn reusable shell or template workflows into composer actions.
• Skills provide reusable instructions and supporting files that the agent

• Resource packs bundle commands, skills, themes, settings, and plugins.
• Themes customize both the TUI and syntax highlighting.
• TypeScript plugins can extend tools, hooks, model behavior, and the app

Use /config to edit configuration, /resources to choose which resources are enabled, and /reload to reload plugins and resources without restarting zaly. These formats are still evolving during alpha.

🖥️ Terminal notes

• Fullscreen mode provides a focused app-like interface. Scrollback mode

• Clipboard support depends on the platform and terminal environment. Ctrl-Y

• Images use the Kitty Graphics Protocol when supported and degrade gracefully

• tmux graphics support depends on terminal passthrough and tmux configuration.

📦 Packages

| Package | Description | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | | @zaly/cli | The zaly terminal app: composer, actions, sessions, providers, permissions, and TUI wiring. | | @zaly/agent | Agent runtime: session loop, tools, permissions, compaction, masking, tasks, and subagents. | | @zaly/ai | Provider/model abstraction: auth, streaming, content, tools, validation, and model metadata. | | @zaly/tui | Terminal UI framework: stream/UI/overlay surfaces, widgets, themes, selection, clipboard, and terminal graphics. | | @zaly/config | Settings, resources, packs, plugins, and configuration schemas. | | @zaly/plugin | Plugin-facing API and loader helpers. | | @zaly/shared | Shared utilities for paths, processes, detection, images, ANSI text, templates, and more. | | @zaly/dev | Internal development CLI for building, testing, linting, formatting, and publishing this monorepo. |

🛠️ Development

This is a Bun workspace monorepo.

bun install
bun test
bun z lint
bun z build

Useful development commands:

bun test packages/agent/test/permissions.test.ts
bun z test --coverage --reporter minimal
bun z fmt

Status

zaly is pre-1.0 and in active development. Public package APIs are not frozen.

License

MIT © Folke Lemaitre