Clearsky

Getting started

From nothing to your own work list in a few minutes. Clearsky runs on your machine with the logins you already have, and asks for no tokens.

  1. What you need

    Node 22 or newer, and git. For real data you also want the GitHub CLI and, if you use Jira, the Atlassian CLI. For the Copilot chat, the GitHub Copilot CLI. The welcome page tells you what's missing, with the command for your system.

    LinuxEverything, including the sandbox (bubblewrap, socat, ripgrep).
    macOSEverything; the sandbox uses the system's own.
    WindowsRun the installer in WSL.

  2. Install

    git clone https://github.com/ethlo/clearsky
cd clearsky
sh scripts/install.sh

    This puts clearsky on your PATH, adds the sandbox runtime for Copilot, and makes ~/.config/clearsky, readable only by you. It never uses sudo: anything that needs a system package is listed with the command to install it. Run it again any time to update.

    Options: --service starts Clearsky at login, --no-sandbox leaves the sandbox out. Without the installer, node bin/clearsky.mjs serve works straight from the checkout.

  3. Try it with demo data

    clearsky try

    This opens Clearsky on 127.0.0.1:7790 with a made-up company, Acme: its PRs, tickets, meetings, a stand-up and a Copilot chat. It needs no logins and reads nothing of yours, so it's also the way to show Clearsky to someone else. Leave demo in the menu, or Ctrl+C, stops it and removes its data.

  4. Start it for real

    clearsky serve      # http://127.0.0.1:7777
clearsky app        # or in a window of its own

    The first time, a welcome page checks what this machine has (Node, git, gh, acli, Copilot, the sandbox, a calendar) and logs you in with a button each:

    • GitHub through gh auth login. Your work organizations are picked from that login.
    • Jira through acli jira auth login --web. Every Jira call goes through acli, so there's no Jira token in Clearsky.
    • Calendar (optional) from GNOME Online Accounts or an iCal link, for Now / Next and the day's schedule.

    That's all the setup there is. Everything else is under Settings, and saved in ~/.config/clearsky/.

  5. Join your team's setup

    If your team shares a setup, join it. It fills in the organizations, stand-up time, Copilot defaults, links and skills your team agreed on, and keeps anything you set yourself. Logins and the sandbox's doors are never part of a pack.

    clearsky join <the team's repo>

    No pack yet? clearsky team init ~/dev/clearsky-team, or Settings → General → Make a team pack, writes one from your own settings, ready to push to a private repo. More about team packs.

  6. Add what else you use

    clearsky add slack-mcp --trust     # Slack mentions, no token
clearsky add confluence            # Confluence for Copilot chats
clearsky add grafana --trust       # logs and metrics, read only
clearsky plugins                   # what's added, and what's available

    Or under Settings → Plugins. You see what a plugin reaches (hosts, programs, files) before any of its code runs, and each one runs in a sandbox of its own. All plugins · write your own.

  7. Make Copilot write like you

    Comments, PR descriptions and Jira replies that Copilot drafts for you are checked against a voice profile, ~/.copilot/voice.md. It stays on your machine and never goes into a repo or team pack. To make one:

    1. Copy 10 to 20 things you wrote yourself into a scratch file: review comments, PR descriptions, tickets, messages. Mix a pushback, a question, an approval and a bug report. Leave out anything you're not allowed to put through an AI tool.
    2. Ask Copilot to turn it into voice.md: 5 to 10 rules on how you write, a checklist for every draft, and 15 short samples with names and keys replaced.
    3. Delete the scratch file, read the profile, and fix whatever doesn't sound like you.

    The full guide, with the prompt and an example.

  8. If something looks off

    clearsky doctor     # the welcome page's checks, in a terminal
clearsky restart    # restart once no Copilot chat is busy

    Starts, restarts and errors are logged to ~/.cache/clearsky/clearsky.log.

Next