Chatminal user guide

Use Chatminal like a workspace you return to, not a terminal you throw away.

This page is for users, not contributors. It covers how to install Chatminal, how sessions and profiles fit together, how layouts behave, and what to expect when you come back to work later.

Install

Install Chatminal

Chatminal is a desktop terminal for people who want their shell sessions to stay organized and easy to resume. Choose the install path that matches your platform and how you prefer to manage updates.

  • Use the install script if you want the fastest terminal-first setup on macOS or Linux.
  • Use Homebrew on macOS if you want install and upgrade through brew.
  • Use the GitHub Release download if you prefer a direct app archive or you are on Windows.
  • Current prebuilt artifacts cover macOS, Linux x86_64, and Windows x64.

bash

Install with Bash

This installs the latest stable release and is the quickest path from a terminal.

curl -fsSL https://chatminal.com/install | bash

brew

Install with Homebrew

Use this on macOS if you want Chatminal managed as a normal cask.

brew tap Khoa280703/chatminal https://github.com/Khoa280703/chatminal
brew install --cask chatminal

windows

Download for Windows

Windows is currently distributed through the latest GitHub Release zip.

start https://github.com/Khoa280703/chatminal/releases/latest

First launch

What happens on first launch

When Chatminal opens for the first time, it starts with your default shell and gives you a clean place to create sessions for real work instead of stacking everything into a single terminal tab.

  • Start with a fresh shell session and confirm your default working environment.
  • Create separate sessions for separate tasks or repositories.
  • Use profiles to group related sessions together.

Sessions

Sessions and profiles

Sessions are the core unit in Chatminal. Each session keeps its own shell, working directory, and activity state. Profiles help you group sessions by project, team, or workflow.

  • Create one session per task, repo, or environment.
  • Move between profiles when you want to switch context without losing your current sessions.
  • Rename sessions so the sidebar reflects what each one is actually for.
  • Use startup commands for sessions you reopen often.

Layouts

Splits and layouts

Chatminal is designed for working across multiple sessions at once. Layouts let you split your workspace, keep important sessions visible, and return to a familiar arrangement later.

  • Split the workspace when you need logs, shell output, and a second task visible at the same time.
  • Use layouts to keep long-running work in view instead of switching back and forth.
  • Saved layouts make it easier to reopen the same workspace shape later.

History

History and resume behavior

Chatminal persists session state so you can come back to work without starting from a blank terminal every time. That includes session history and the structure of your workspace.

  • Session history can be kept so past output is still available when you return.
  • Reopening the app is meant to feel like resuming work, not relaunching from zero.
  • If you want a clean slate, you can clear history and reset the session context.

Startup

Startup commands

If a session always begins the same way, save a startup command. It is useful for opening a project, attaching to a tool, or restoring a routine shell flow quickly.

  • Use startup commands for sessions you repeat every day.
  • Keep them focused on getting you back to a working state quickly.
  • Treat them as convenience, not as a full deployment script.

FAQ

Common questions

The current product path is desktop-first and session-focused. If you are deciding whether Chatminal fits your workflow, these are the questions that matter most.

  • Does it support multiple sessions? Yes, that is a core part of the product.
  • Can I organize work into profiles? Yes, profiles are part of the stored workspace model.
  • Does it remember layouts and history? Yes, persistence is built into the runtime and store.
  • Is this page for contributors? No. This page is written for end users, not for people hacking on the repo.