Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ name: Validate setup
on: [push, pull_request, workflow_dispatch]
jobs:
test:
runs-on: ubuntu-latest
runs-on: ubuntu-24.04
strategy:
matrix:
python: ['3.9', '3.12']
Expand Down
6 changes: 5 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,10 @@ Missing Zsh and other base tools are installed automatically on Ubuntu/Debian
without sudo. Existing base programs, Vite+, and uv are reused. If bootstrap
prerequisites are missing, `./install.sh --install-prerequisites` offers the
administrative package installation and index refresh before continuing.
On an interactive first run, the installer also offers Git author and optional
GitHub CLI account setup. See [Git and GitHub profiles](docs/developer-workflow.md#git-and-github-profiles).
It also offers an optional [AI skill manager](docs/developer-workflow.md#ai-skills)
for Codex and Claude Code; run `skill-manager` anytime to add or remove skills.

Choose a **Nerd Font** in your terminal settings to display prompt icons. In WSL
or SSH, configure the font on the desktop client. Installation leaves your
Expand All @@ -91,7 +95,7 @@ that registration is missing; pass `--skip-mcp` to skip it.

| Area | Included |
| --- | --- |
| Shell and prompt | Zsh, Oh My Posh, two bundled themes, autosuggestions, syntax highlighting, completion, persistent history |
| Shell and prompt | Zsh, Oh My Posh, upstream theme selection and two bundled themes, autosuggestions, syntax highlighting, completion, persistent history |
| Search and navigation | fzf, fd, ripgrep, zoxide, custom command picker |
| Files and previews | eza, bat, Yazi, jq |
| Git and sessions | lazygit, delta, tmux, project session helper |
Expand Down
6 changes: 6 additions & 0 deletions bin/git-profile
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
#!/usr/bin/env python3
"""Manage Git author details and GitHub CLI accounts."""
from pathlib import Path
import runpy

runpy.run_path(str(Path(__file__).resolve().parents[1] / "scripts/git_profiles.py"), run_name="__main__")
6 changes: 6 additions & 0 deletions bin/skill-manager
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
#!/usr/bin/env python3
"""Browse and manage local AI agent skills."""
from pathlib import Path
import runpy

runpy.run_path(str(Path(__file__).resolve().parents[1] / 'scripts/skill_manager.py'), run_name='__main__')
2 changes: 1 addition & 1 deletion config/zsh/zshrc
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ if [[ -r "$_dev_plugin_dir/zsh-autosuggestions/current/zsh-autosuggestions.zsh"
fi

if (( $+commands[oh-my-posh] )); then
eval "$(oh-my-posh init zsh --config "$LINUX_SETUP_DIR/config/oh-my-posh/quick-term.omp.json")"
eval "$(oh-my-posh init zsh --config "${LINUX_SETUP_POSH_THEME:-$LINUX_SETUP_DIR/config/oh-my-posh/quick-term.omp.json}")"
fi

# These stay private to the device. Portable customizations belong in this repo.
Expand Down
24 changes: 13 additions & 11 deletions docs/customization.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,18 +12,20 @@ for Zsh; the `iterm2` name does not require the iTerm2 application.
| Quick-term | Orange accents, two-line prompt, duration and clock, compact command history | [`quick-term.omp.json`](../config/oh-my-posh/quick-term.omp.json) |
| iTerm2 | Blue and lime segments, exit-status color, rocket prompt, contextual segments | [`iterm2.omp.json`](../config/oh-my-posh/iterm2.omp.json) |

To try the alternative in your current Zsh session:
Select any theme from the [Oh My Posh theme gallery](https://ohmyposh.dev/docs/themes/)
by setting its name in `~/.config/linux-setup-local/zshenv`:

```zsh
eval "$(oh-my-posh init zsh --config "$LINUX_SETUP_DIR/config/oh-my-posh/iterm2.omp.json")"
export LINUX_SETUP_POSH_THEME='paradox'
```

To make it the shared default, change the `--config` path in
[`config/zsh/zshrc`](../config/zsh/zshrc) from `quick-term.omp.json` to
`iterm2.omp.json`, then run `reload`. To keep the choice private to one device,
put the initialization command above in `~/.config/linux-setup-local/zshrc`,
which loads after the shared prompt configuration. Remove that override to use
the shared default again.
Create the directory and file if needed, then run `reload`. Oh My Posh also
accepts a local configuration path or HTTPS URL in this variable. For the bundled
iTerm2 configuration, use `export LINUX_SETUP_POSH_THEME="$LINUX_SETUP_DIR/config/oh-my-posh/iterm2.omp.json"`.
Remove the setting to restore the bundled quick-term default. Upstream theme names
and URLs require network access and are cached by Oh My Posh; local files work
offline. The installed Oh My Posh version determines which upstream themes are
available.

Use a Nerd Font in your terminal emulator. Font, terminal colors, Git state,
screen width, and available hardware affect the appearance. Battery and Python
Expand Down Expand Up @@ -56,9 +58,9 @@ linux-setup/

Add shared aliases to `config/zsh/aliases.zsh`, functions to
`config/zsh/functions.zsh`, and executable scripts to `bin/`. Rerun the installer
to link new scripts. Edit the active theme in
`config/oh-my-posh/quick-term.omp.json`. Change its path in `config/zsh/zshrc` to
switch themes. Use `reload` after changing shell initialization or prompt settings.
to link new scripts. Edit the bundled default in
`config/oh-my-posh/quick-term.omp.json`. Use `reload` after changing shell
initialization or prompt settings.

Private or device-specific additions go in:

Expand Down
57 changes: 57 additions & 0 deletions docs/developer-workflow.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,63 @@ exec zsh
Use the persistent checkout for installation, rather than a temporary review
worktree. Configuration-only installation keeps existing tools and their versions.

## Git and GitHub profiles

Run `./install.sh --github-setup` from the setup checkout to fill missing global
Git author settings, install GitHub CLI if needed, and add accounts. You can also
run `git-profile add` later: it offers GitHub CLI login, or you can reuse an
account already logged in. Add each GitHub username with its commit author name
and email, then use:

```sh
git-profile list
cd ~/projects/my-repository
git-profile use my-github-username
```

`use` selects the account in GitHub CLI and sets `user.name` and `user.email`
for the current repository. GitHub CLI's active account is shared across terminal
sessions for that host, so switching accounts affects other repositories and
terminals too; their saved repository author settings do not change. Run
`gh auth status` to inspect accounts. HTTPS Git credentials use the GitHub CLI
account only if its credential helper is configured (for example, with
`gh auth setup-git`); SSH authentication depends on your SSH configuration.
Environment tokens such as `GH_TOKEN` can override saved GitHub CLI accounts.
GitHub CLI manages credentials separately and may store tokens in a plain-text
file if no credential store is available. The profile file contains only author
details and usernames, not tokens. Use an email associated with the intended
GitHub account, including its no-reply address if desired.

## AI skills

Run `skill-manager` to install, list, or remove local skills. From a checkout that
has not been installed, run `python3 scripts/skill_manager.py` instead. Select
Codex or Claude Code, then global or project scope. For project scope, provide
the path of an existing project directory; enter `.` to use the current directory.
The install menu groups the catalog by work area and accepts multiple selections.

| Agent | Global directory | Project directory |
| --- | --- | --- |
| Codex | `~/.agents/skills/` | `<project>/.agents/skills/` |
| Claude Code | `~/.claude/skills/` | `<project>/.claude/skills/` |

These are local agent skills, not skills uploaded to ChatGPT or another hosted
service. The manager lists and removes skill directories in the selected location,
including skills installed by other tools; it displays the exact paths and asks
for confirmation before deleting. It does not overwrite existing skills. Skills
installed as symlinks are removed by unlinking them; their targets are kept. Skills
in other discovery locations, such as `~/.codex/skills`, are not listed there.

The catalog includes UI/UX Pro Max, Humanizer, frontend design, web guidelines,
React, testing, DevOps, and writing skills. OpenAI's Codex-specific skills are
offered only for Codex. The catalog records upstream repositories and commit
IDs in [`skills.catalog.json`](../skills.catalog.json). Downloads need network
access; files are then installed locally with their supporting resources. UI/UX
Pro Max's plugin-specific script paths are adapted to the selected installation
directory, so reinstall it after moving that directory. Review the displayed
source URLs: third-party skills contain instructions and may include scripts.
Restart the agent session if it does not immediately discover new skills.

## Check a checkout

```sh
Expand Down
19 changes: 18 additions & 1 deletion docs/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,10 @@ exec zsh
linux-doctor
```

The preflight checks prerequisites before installation. The dry run describes the
The preflight checks prerequisites before installation. Its GitHub homepage probe
is advisory: a failure may not reflect access to release downloads, which are
checked during installation. If installation fails, do not run `exec zsh` until
the error has been resolved and installation succeeds. The dry run describes the
installation without applying it. Downloaded artifacts are verified against the
SHA-256 values in `tools.lock.json`; repeat installs reuse verified downloads.

Expand Down Expand Up @@ -77,6 +80,20 @@ installation, including Zsh. At completion, the installer prints an `exec` comma
with the full Zsh path so it also works before your current shell has added
`~/.local/bin` to `PATH`.

On an interactive normal installation, the installer asks for a Git author name
and email only when the corresponding global value is missing. It then offers
GitHub CLI installation and account setup on the first interactive run. Existing
values and an existing `gh` installation are preserved. Non-interactive runs,
preflight, dry runs, and configuration-only runs do not prompt. You can revisit
the account flow with `./install.sh --github-setup`, or install just the optional
CLI with `./install.sh --install-gh`. The GitHub CLI download is pinned and
checksum-verified like the other managed tools.

The first interactive installation also offers the optional AI skill manager.
Choose Codex or Claude Code, an area of work, and global or project scope. You
can skip this step and run `skill-manager` later. See
[AI skills](developer-workflow.md#ai-skills) for sources and removal.

The PostgreSQL dependency is the `psql` client only. Installing it does not create
a database cluster or start a server. Your applications retain responsibility for
their Node/Python versions and dependency lockfiles.
Expand Down
121 changes: 121 additions & 0 deletions scripts/git_profiles.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
"""Interactive Git identity and GitHub account helpers; never store credentials."""
import argparse
import json
import os
from pathlib import Path
import shutil
import subprocess
import sys
import tempfile


def profiles_path():
return Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config")) / "linux-setup-local/git-profiles.json"


def load_profiles():
path = profiles_path()
return json.loads(path.read_text()) if path.exists() else {}


def save_profiles(profiles):
path = profiles_path()
path.parent.mkdir(parents=True, exist_ok=True)
fd, name = tempfile.mkstemp(prefix=".git-profiles-", dir=path.parent)
try:
with os.fdopen(fd, "w") as stream:
json.dump(profiles, stream, indent=2, ensure_ascii=False)
stream.write("\n")
os.replace(name, path)
finally:
if os.path.exists(name):
os.unlink(name)


def ask_yes(prompt, default=False):
suffix = " [Y/n] " if default else " [y/N] "
while True:
answer = input(prompt + suffix).strip().lower()
if not answer:
return default
if answer in ("y", "yes"):
return True
if answer in ("n", "no"):
return False
print("Please answer yes or no.")


def ask_required(prompt, default=""):
while True:
answer = input(prompt + (f" [{default}]" if default else "") + ": ").strip() or default
if answer:
return answer
print("A value is required.")


def configure_identity():
for key, label in (("user.name", "Git author name"), ("user.email", "Git author email")):
result = subprocess.run(["git", "config", "--global", "--get", key], capture_output=True, text=True)
if result.returncode not in (0, 1):
raise RuntimeError(f"Cannot read global Git setting {key}: {result.stderr.strip()}")
if not result.stdout.strip():
value = ask_required(label)
subprocess.run(["git", "config", "--global", key, value], check=True)


def add_profile():
if not shutil.which("gh"):
raise RuntimeError("GitHub CLI is missing. Run ./install.sh --install-gh first.")
if ask_yes("Authenticate another GitHub account now?", default=True):
subprocess.run(["gh", "auth", "login"], check=True)
username = ask_required("GitHub username")
profiles = load_profiles()
if username in profiles and not ask_yes(f"Replace saved author details for {username}?"):
return
name = ask_required("Git author name")
email = ask_required("Git author email")
profiles[username] = {"name": name, "email": email}
save_profiles(profiles)
print(f"Saved {username}. Use git-profile use {username} inside a repository.")


def use_profile(username):
profiles = load_profiles()
if username not in profiles:
raise RuntimeError(f"No saved profile for {username}. Run git-profile add first.")
subprocess.run(["git", "rev-parse", "--git-dir"], check=True, stdout=subprocess.DEVNULL)
if not shutil.which("gh"):
raise RuntimeError("GitHub CLI is missing. Run ./install.sh --install-gh first.")
subprocess.run(["gh", "auth", "switch", "--hostname", "github.com", "--user", username], check=True)
for key, value in (("user.name", profiles[username]["name"]), ("user.email", profiles[username]["email"])):
subprocess.run(["git", "config", "--local", key, value], check=True)
print(f"Selected {username}: repository author updated; GitHub CLI active account changed for github.com.")


def main():
parser = argparse.ArgumentParser(description=__doc__)
sub = parser.add_subparsers(dest="action", required=True)
sub.add_parser("add", help="Add an account and its Git author details")
sub.add_parser("list", help="List saved profiles")
use = sub.add_parser("use", help="Select an account and set this repository's author")
use.add_argument("username")
args = parser.parse_args()
if args.action == "add":
add_profile()
elif args.action == "use":
use_profile(args.username)
else:
profiles = load_profiles()
for username, profile in sorted(profiles.items()):
print(f"{username}: {profile['name']} <{profile['email']}>")
if not profiles:
print("No profiles saved. Run git-profile add.")
return 0


if __name__ == "__main__":
try:
sys.exit(main())
except (RuntimeError, OSError, subprocess.CalledProcessError, ValueError, EOFError) as error:
print(f"git-profile: {error}", file=sys.stderr)
sys.exit(1)
9 changes: 6 additions & 3 deletions scripts/preflight.py
Original file line number Diff line number Diff line change
Expand Up @@ -101,12 +101,15 @@ def check(root, config, data, state, cache, bin_dir, *, config_only=False, netwo
if network and not config_only and not errors:
try:
ssl.create_default_context()
request = urllib.request.Request("https://github.com/", method="HEAD", headers={"User-Agent": "linux-setup/preflight"})
request = urllib.request.Request("https://github.com/", headers={"User-Agent": "linux-setup/1"})
with urllib.request.urlopen(request, timeout=8):
pass
messages.append("GitHub HTTPS and certificate verification succeeded. Individual release downloads are verified during installation.")
except (OSError, ValueError, urllib.error.URLError):
errors.append("Cannot reach GitHub over verified HTTPS. Check network/proxy access and the system CA certificates; keep TLS verification enabled. On Ubuntu/Debian, --install-prerequisites installs ca-certificates.")
except (OSError, ValueError, urllib.error.URLError) as exc:
# A homepage probe can be blocked independently of release downloads.
# Let the actual checksum-verified downloads determine availability.
detail = f"HTTP {exc.code}" if isinstance(exc, urllib.error.HTTPError) else str(getattr(exc, "reason", exc))
messages.append(f"Warning: GitHub HTTPS probe failed ({detail}). Installation will still try the actual downloads with TLS verification enabled. Check proxy settings and CA certificates if downloads fail; on Ubuntu/Debian, --install-prerequisites installs ca-certificates.")
elif not network or config_only:
messages.append("Network check skipped; no files were downloaded.")
messages.append("Optional: a Nerd Font on the terminal-rendering device; ffmpeg, Poppler, and 7-Zip for extra Yazi previews.")
Expand Down
Loading
Loading