Skip to content

Your team of AI agents, on your Mac, Windows or Linux. Agents that talk in channels, write code, review each other and use your tools, on the Claude Code, Codex, OpenCode or Pi you already have. Anything that touches the real world waits for your yes.

7.3 KB
Raw Blame

Arch Linux and CachyOS with Niri

This guide covers running Tucano on Arch Linux and its family, and repeating the validation in a Niri/Wayland session. The run recorded below was done on CachyOS. It covers the source code and a basic Electron start; installing from the AppImage and full desktop integration still need testing.

Installing the AppImage

Download the AppImage for your architecture from the releases page. For x86_64, the 0.2.0 file is tucano-linux-x86_64.AppImage; for ARM64, tucano-linux-arm64.AppImage.

In the download folder, for x86_64:

chmod +x tucano-linux-x86_64.AppImage
./tucano-linux-x86_64.AppImage

If it fails with a FUSE error, check that fuse2 is installed (pacman -Q fuse2). The package is in the Arch Linux repositories. Don't run the app as root or turn off the sandbox to get around a start-up failure.

install.sh also picks the AppImage on systems without apt/dpkg and adds an entry to the applications menu. On Arch, don't use the .deb. Installing and updating the AppImage was not run in this validation.

The validated environment

Validated on 2026-10-30, on the 0.2.0 code with this contribution's Ghostty support:

Component Version or value observed
Distribution CachyOS, rolling, ID_LIKE=arch
Architecture x86_64
Session XDG_SESSION_TYPE=wayland, XDG_CURRENT_DESKTOP=niri
Niri 26.04
Ghostty 1.3.1-arch2.2
Kitty 0.49.2
Alacritty 0.17.0 (94e7c887)
Node.js 24.16.0
npm 11.16.0
Electron 44.8.0
FUSE fuse2 2.9.9-6 installed, AppImage not tested

To record another environment, use cat /etc/os-release, uname -m, niri --version, ghostty --version, kitty --version, alacritty --version, node --version and npm --version. Record the session type and the desktop too, without publishing the full contents of the environment variables.

Checks run

In the checkout, with Node.js 24 or later:

npm ci
npm test -- test/platform.test.ts
npm run typecheck
npm test
npm run build

Results observed:

Check Result
Platform tests 22 passed, 6 skipped by platform
Typecheck Passed
Full suite 32 files passed; 261 tests passed, 14 skipped
Build Passed
Ghostty, opened for real with what terminalCommand returns Command ran, marker in a temporary file confirmed
Kitty, opened for real with what terminalCommand returns Command ran, marker in a temporary file confirmed
Alacritty, opened for real with what terminalCommand returns Command ran, marker in a temporary file confirmed
Electron with --ozone-platform=wayland Window visible, .sidebar present, no pageerror event in the basic test
Notifications API Notification.isSupported() returned true; delivery not tested
Electron's keyring isEncryptionAvailable() returned false, backend basic_text

Skipped tests don't count as verified features. There was no real sign-in and no tokens spent: the start used TUCANO_FAKE_ENGINES=1 and temporary data. The graphical test doesn't cover every flow of the interface.

Ghostty, Kitty and Alacritty

On Linux, Ghostty and Alacritty take -e followed by the program and its arguments; Kitty takes the program directly. Tucano passes sh, -c and the sign-in command as separate arguments and keeps the shell open after the command, as with the other Linux terminals. Desktop terminals already earlier in the list still win when they are installed too.

Kitty and Alacritty were already supported. This contribution adds Ghostty and regression tests for the three terminals, including executable paths with spaces and the preference for the desktop's terminal. The choice follows the order of Tucano's list; it doesn't look up which terminal the session has set as its default.

To run the command Tucano produces for real in each of the three installed terminals, at the root of the checkout:

node --input-type=module <<'NODE'
import { terminalCommand } from './src/core/platform.ts'
import { spawnSync } from 'node:child_process'
import { mkdtempSync, readFileSync, rmSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'

for (const bin of ['ghostty', 'kitty', 'alacritty']) {
  const dir = mkdtempSync(join(tmpdir(), 'tucano-terminal-'))
  try {
    const marker = join(dir, 'result')
    const terminal = terminalCommand(`printf '%s' 'ok' > '${marker}'`, 'linux', candidate => candidate === bin)
    if (!terminal) throw new Error(`${bin} was not selected`)
    const result = spawnSync(terminal.bin, terminal.args, {
      env: { ...process.env, SHELL: '/bin/true' },
      timeout: 15000
    })
    if (result.error) throw result.error
    if (result.status !== 0) throw new Error(`${bin} exited with ${result.status}: ${result.stderr}`)
    if (readFileSync(marker, 'utf8') !== 'ok') throw new Error(`${bin} marker check failed`)
    console.log(`${bin} check passed`)
  } finally {
    rmSync(dir, { recursive: true, force: true })
  }
}
NODE

SHELL=/bin/true applies only to the test's process and closes the window after the command runs. Keeping the interactive shell open is covered by the argument composition in the unit test; using that shell by hand and the OAuth sign-in still need validation.

Desktop checks still to do

After npm run build, open a separate instance with temporary data and simulated agents. Quit the app from its menu before deleting the temporary folder:

validation_data=$(mktemp -d)
TUCANO_DATA="$validation_data" TUCANO_FAKE_ENGINES=1 \
  ./node_modules/.bin/electron . --ozone-platform=wayland
rm -r -- "$validation_data"
Area What to check
Keyring Confirm a Secret Service or KWallet is available and unlocked in the session; check that Electron picks a secure backend before trying to store a throwaway credential
Noctalia tray Confirm the icon shows, the window reopens after closing it, and quitting from the tray menu works
Notifications Confirm delivery, the click, and the return to the conversation
Terminals and sign-in Ask for the sign-in from the interface, finish it with a harness and check the return to Tucano; repeat with each terminal to validate
Open at login With a persistent install, turn the option on and check ~/.config/autostart/tucano.desktop (or the XDG_CONFIG_HOME folder); then test a new login to the session
AppImage Check that it opens, the applications menu, the packaged resources, and updating

gnome-keyring was installed in the tested environment, but that wasn't enough to make encryption available to Electron. Tucano refuses to store credentials with basic_text or without encryption available. Don't force that backend to get around the protection, and don't use real credentials while the keyring isn't working.

Tucano writes an XDG entry for opening at login on Linux. Whether it runs depends on the Niri session's setup. Don't turn on Open at login from the checkout or from the temporary instance above: the development executable isn't a persistent install.

When reporting a result, include Tucano's version or commit, the distribution, the compositor, the terminal, how it was installed, the steps run and the expected and observed result. Don't include tokens, credentials or logs you haven't reviewed.