Skip to content

getting-started.md

Latest commit

 

History

History
88 lines (58 loc) · 5.46 KB

getting-started.md

File metadata and controls

88 lines (58 loc) · 5.46 KB
Raw

Getting started

Requirements

  • macOS 26 or later, on Apple silicon or Intel
  • Xcode 26 or later (Swift 6), to build it yourself

Install

Download Codec-<version>.dmg from the latest release, open it and drag Codec to Applications.

Codec isn't notarized by Apple yet, so the first time you open it, macOS says it can't check it for malicious software. Open System Settings › Privacy & Security, scroll to Security, choose Open Anyway beside Codec and confirm. Updates Codec installs itself don't ask again; a version you download by hand does. Permissions you've given Codec, like Full Disk Access, carry over.

Or install it with Homebrew, from the cask in this repository (macOS asks the same way the first time):

brew tap srozen/codec https://github.com/srozen/codec
brew install --cask srozen/codec/codec

Updates

Once a day, Codec asks GitHub for its latest release. When there's a newer one, it posts a notification, and Codec › Check for Updates… becomes Update to Codec 1.2.0…: choose it, or click the notification, to see what's new. Skip This Version stops it from announcing that one.

Install downloads the new version and gets it ready beside this one. Then Install and Relaunch puts it in place and reopens Codec with your windows, tabs and splits (programs running in them stop, and Codec asks first), or Install on Quit leaves it for the next time you quit. Codec only installs a version signed with the same certificate as the one you have, and it checks the download against the checksum GitHub lists for it.

Where Codec can't replace itself, the alert offers Download instead, which opens the new disk image: drag Codec to Applications, then reopen it. That's when it runs from the disk image or from Downloads, or from a folder you can't write to. If Homebrew installed Codec, Upgrade puts brew upgrade --cask srozen/codec/codec at the prompt for you to run instead.

The check sends nothing about you, your Mac or what you run. Turn it off in Settings › Updates; Check for Updates… still works.

Build from source

git clone https://github.com/srozen/codec.git
cd codec
make run

make run builds build/Codec.app in release and opens it. Drag it to /Applications to keep it, or run it from where it is: the next make run rebuilds it in place, so you always run what's in your checkout.

Other targets:

make build     # debug build only
make test      # build and run all tests
make app       # build build/Codec.app without opening it

make builds with two jobs to keep memory use reasonable; override with make run JOBS=8. Without make: scripts/build-app.sh [debug|release], swift test.

Sounds

Codec plays short codec cues: a call when a background pane needs you, and, if you turn them on, a lock-on when a pane opens and a static burst when one closes or its shell crashes. Put codec_call.mp3, codec_lock.mp3 and codec_exit.mp3 in Resources/Sounds/ and the build bundles them. They're git-ignored, since they're game audio; without them Codec synthesizes similar cues. See Settings › Alerts.

First steps

Open a few panes and try the things Codec adds on top of a terminal:

  1. Split the window with ⌘D (right) or ⇧⌘D (down). New panes open in the current directory.
  2. Run a few commands, then press ⇧⌘L: the Commands sidebar lists them, with their output, so you can go back to any of them.
  3. Press ↑ at an empty prompt for the history menu, or ⌘Y to search everything you've run, anywhere.
  4. Press ⇧⌘E for the file tree of the project you're in, and click a file to read it beside the terminal.
  5. Press ⇧⌘I for Intel: save a command you'll need again, with blanks to fill in next time.
  6. Press ⇧⌘P for the command palette: every action, theme and tab, fuzzy-searched.

Shell integration (zsh)

Codec loads a small hook script into zsh through ZDOTDIR, then your own startup files (.zshenv, .zprofile, .zshrc, .zlogin), unchanged. The hooks report:

  • where each prompt starts and ends, and where each command's output starts and ends (OSC 133 marks),
  • the working directory (OSC 7),
  • each command's text, exit status and duration.

That's what the Commands sidebar, the status bar, ⌘↑ / ⌘↓ between commands, Copy Output, history with folders and durations, notifications for long commands, the editable command line and Codec's prompt are built on.

Turn it off in Settings › Shell › Shell integration; it applies to new panes. Other shells (bash, fish, nushell…) run as plain terminals: set one in Settings › Shell.

Where Codec keeps things

What Where
Settings, window state, and the windows and tabs to reopen ~/Library/Preferences (the app's defaults)
What each pane showed, kept when you quit ~/Library/Application Support/Codec/Saved Panes, readable only by you
Command history ~/Library/Application Support/Codec/history.jsonl, plus your zsh history file, which Codec reads but never changes
Your Intel ~/.codec/intel
A project's Intel .codec/intel in its git repository
The shell integration scripts and your prompt ~/Library/Application Support/Codec/shell-integration
Which Python environments you let Codec activate venv-decisions in that same folder, one line per answer