Terminal Module

The Keystone Terminal module (keystone.terminal) provides a comprehensive, opinionated command-line development environment. It is designed to work consistently across NixOS, macOS, and other Linux distributions via Home Manager.

Enable the Module

To enable the terminal environment in your Home Manager configuration:

keystone.terminal.enable = true;

This installs and configures:

• Helix: Modal text editor (default)
• Zsh: Interactive shell with Starship prompt
• Zellij: Terminal multiplexer
• Lazygit: Git TUI
• Git: Configured with LFS and sensible defaults
• Utilities: eza, ripgrep, htop, zoxide, direnv, yazi

Helix Editor

Keystone configures Helix as the default editor (EDITOR and VISUAL environment variables are set to hx).

Key Features

• Language Support: Pre-configured LSPs for Bash, Markdown, Nix, TypeScript, Docker, YAML, JSON, and more.
• Theme: Uses kinda_nvim theme by default.
• Soft Wrap: Enabled by default with a text width of 120 columns.

Keybindings (Normal Mode)

Markdown Preview

The Markdown preview feature (F6) uses a robust helper script (helix-preview-markdown) that:

1. Pipes the full content of the current file (even if unsaved) to Pandoc.
2. Renders it to /tmp/helix-preview.html.
3. Opens the HTML file in your system's default browser (via xdg-open).
4. Copies the URL (file:///tmp/helix-preview.html) to your clipboard (using wl-copy on Linux or pbcopy on macOS) so you can paste it into a different browser if preferred.

Language Servers

The module installs and configures the following language servers automatically:

• Markdown: marksman, harper-ls (grammar checking)
• Nix: nixfmt
• Bash: bash-language-server
• TypeScript: typescript-language-server, prettier
• Docker: docker-langserver, docker-compose-langserver
• YAML: yaml-language-server
• Ruby: ruby-lsp, solargraph

Shell Environment

Zsh

• Prompt: Starship prompt is configured for a minimal, informative interface.
• Navigation: Zoxide is enabled for fast directory jumping (z <dir>).
• Aliases:
  • ls, l -> eza -1l (modern ls replacement)
  • grep -> rg (ripgrep)
  • g -> git
  • lg -> lazygit
  • zs -> zesh connect (session manager)

Zellij

Zellij is configured with sensible keybindings and acts as the default terminal multiplexer.

hwrekey — Secrets Rekeying

The hwrekey command automates re-encrypting agenix secrets with your YubiKey and (optionally) handling the full submodule commit/push/flake-update workflow.

Enable

hwrekey is available when keystone.terminal.ageYubikey.enable = true.

keystone.terminal.ageYubikey = {
  enable = true;
  identities = [ "AGE-PLUGIN-YUBIKEY-..." ];
  # Optional: enable submodule workflow
  secretsFlakeInput = "agenix-secrets";
};

Usage

cd agenix-secrets
hwrekey

What It Does

1. Runs agenix --rekey using the YubiKey identity file (touch prompt per secret, no SSH password)
2. If secretsFlakeInput is set:
   • Commits and pushes the rekeyed secrets in the current (submodule) repo
   • Runs nix flake update <secretsFlakeInput> in the parent repo
   • Commits the submodule pointer + flake.lock together in the parent repo
3. If secretsFlakeInput is null, only runs the rekey — you commit manually

Options

When to Use

Run hwrekey after any change to secrets.nix that adds or removes key recipients (e.g., enrolling a new YubiKey, adding a new host key, removing a decommissioned machine). See Hardware Keys for the full YubiKey enrollment workflow.

Conventions

The conventions module writes keystone conventions to each CLI coding tool's native instruction file path at build time:

• ~/.claude/CLAUDE.md (Claude Code)
• ~/.gemini/GEMINI.md (Gemini CLI)
• ~/.codex/AGENTS.md (Codex)
• OpenCode reads ~/.claude/CLAUDE.md via legacy compatibility

keystone.terminal.conventions = {
  enable = true;            # Default: true
};

The archetype (set per-agent via keystone.os.agents.<name>.archetype, default "engineer") controls which convention set is inlined vs referenced. See conventions/tool.cli-coding-agents.md for details on each tool's file discovery.

DeepWork

The DeepWork module integrates workflow-driven development with quality gates into the terminal environment.

keystone.terminal.deepwork = {
  enable = true;            # Default: true
};

When enabled, the DEEPWORK_ADDITIONAL_JOBS_FOLDERS environment variable is set and injected into the generated DeepWork MCP server configs, allowing spawned MCP sessions to discover shared project job definitions alongside the built-in ones.

Notes

Keystone supports a shared zk notebook model for both human note-taking and agent-generated notes and reports. The user-facing guide is Notes.

For terminal users, the most relevant parts are:

• zk for manual note creation and search,
• /notes.project for hub notes,
• /notes.report for report capture,
• /notes.doctor for notebook repair and normalization, and
• /notes.process_inbox for inbox review.

Use the notes guide for the workflow and the conventions for the authoritative schema and policy details.

Projects and sessions

Keystone project sessions are note-backed. Active project hub notes in ~/notes/index/ define the valid project set, related repos, and the context that pz uses to launch Zellij sessions.

Use Projects and pz for:

• hub note requirements,
• repo and worktree path conventions,
• pz list and pz <project> usage, and
• project-to-agent handoff from a running session.

Personal Information Management

Keystone integrates the Pimalaya CLI suite for email, calendars, contacts, and timers:

Calendar and contacts auto-default credentials from the mail config. See Personal Information Management for full usage documentation and Agents for agent-mail usage (structured email templates for OS agents).