ctx-tui 0.1.0__tar.gz

ctx_tui-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Barlow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ctx_tui-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: ctx-tui
+Version: 0.1.0
+Summary: Manage repo-scoped work contexts: fresh checkouts wrapped in terminal multiplexer sessions
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: textual>=8.2.8
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# ctx
+
+The way I write code has changed. With agents, I context-switch more, and the
+time it takes to spin up or tear down a context became increasingly noticeable.
+I didn't enjoy the `git worktree` UX, so I ended up maintaining multiple
+long-lived clones of the same repository nestled in different tmux sessions to
+work concurrently. This worked well for me, but it wasn't exactly elegant. So
+here we are.
+
+`ctx` lets you manage repo-scoped work contexts: each context is a fresh full
+checkout on its own local branch, wrapped in a terminal multiplexer session
+with your panes already laid out.
+
+
+Disclaimer: this is fully vibe-coded.
+
+## Install
+
+```sh
+uv tool install ctx-tui
+```
+
+## Usage
+
+Run `ctx` to manage contexts and repos interactively in the TUI (`?` lists
+the keybindings). The same operations are available as subcommands:
+
+```sh
+ctx repo add https://github.com/Michael-JB/papaya-nvim.git   # once per repo
+ctx new papaya-nvim my-cool-feature   # fresh checkout + session, jump in
+# ...work, commit, push...
+ctx rm my-cool-feature                # tear it all down again
+```
+
+More detail:
+
+```sh
+# List contexts with their repo, branch, and status:
+ctx list
+
+# Contexts branch off the up-to-date default branch. To base one on another branch:
+ctx new papaya-nvim follow-up -b other-base
+
+# Re-attach to a context, recreating its session if needed:
+ctx open my-cool-feature
+
+# List registered repos, or remove some (their contexts are left alone):
+ctx repo list
+ctx repo rm papaya-nvim
+```
+
+## Configuration
+
+Optional, at `$XDG_CONFIG_HOME/ctx/config.toml`. Directories default under
+`$XDG_DATA_HOME/ctx/`; the example shows the usual fallback paths. All fields
+shown with their defaults, except the layout: that defaults to a single shell
+pane, so a custom tree is shown instead.
+
+```toml
+contexts_dir = "~/.local/share/ctx/contexts"  # where checkouts live
+repos_dir = "~/.local/share/ctx/repos"        # internal storage for registered repos
+branch_prefix = ""                            # work branch prefix, e.g. "jane/"
+multiplexer = "tmux"                          # or "zellij" (requires zellij >= 0.44)
+
+# The pane layout: a tree of panes and "row"/"column" splits ("row" = side
+# by side, "column" = stacked). A pane runs `command` (default: a shell) in
+# the checkout; at most one pane may set `focus`.
+[layout]
+split = "row"
+
+[[layout.panes]]
+split = "column"
+[[layout.panes.panes]]
+command = "lazygit"
+[[layout.panes.panes]]
+command = "nvim"
+
+[[layout.panes]]
+command = "claude"
+focus = true
+```
+
+### Environment variables
+
+Fresh checkouts don't carry untracked files like `.env`. All contexts of a
+repo share the parent directory `<contexts_dir>/<repo>/`; you could, for
+example, use a tool like [direnv](https://direnv.net) to export env vars in
+all of a repo's contexts from a single `.envrc` there:
+
+```sh
+echo 'export MY_SECRET=some-value' > <contexts_dir>/papaya-nvim/.envrc
+direnv allow <contexts_dir>/papaya-nvim
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).

ctx_tui-0.1.0/README.md

@@ -0,0 +1,97 @@
+# ctx
+
+The way I write code has changed. With agents, I context-switch more, and the
+time it takes to spin up or tear down a context became increasingly noticeable.
+I didn't enjoy the `git worktree` UX, so I ended up maintaining multiple
+long-lived clones of the same repository nestled in different tmux sessions to
+work concurrently. This worked well for me, but it wasn't exactly elegant. So
+here we are.
+
+`ctx` lets you manage repo-scoped work contexts: each context is a fresh full
+checkout on its own local branch, wrapped in a terminal multiplexer session
+with your panes already laid out.
+
+
+Disclaimer: this is fully vibe-coded.
+
+## Install
+
+```sh
+uv tool install ctx-tui
+```
+
+## Usage
+
+Run `ctx` to manage contexts and repos interactively in the TUI (`?` lists
+the keybindings). The same operations are available as subcommands:
+
+```sh
+ctx repo add https://github.com/Michael-JB/papaya-nvim.git   # once per repo
+ctx new papaya-nvim my-cool-feature   # fresh checkout + session, jump in
+# ...work, commit, push...
+ctx rm my-cool-feature                # tear it all down again
+```
+
+More detail:
+
+```sh
+# List contexts with their repo, branch, and status:
+ctx list
+
+# Contexts branch off the up-to-date default branch. To base one on another branch:
+ctx new papaya-nvim follow-up -b other-base
+
+# Re-attach to a context, recreating its session if needed:
+ctx open my-cool-feature
+
+# List registered repos, or remove some (their contexts are left alone):
+ctx repo list
+ctx repo rm papaya-nvim
+```
+
+## Configuration
+
+Optional, at `$XDG_CONFIG_HOME/ctx/config.toml`. Directories default under
+`$XDG_DATA_HOME/ctx/`; the example shows the usual fallback paths. All fields
+shown with their defaults, except the layout: that defaults to a single shell
+pane, so a custom tree is shown instead.
+
+```toml
+contexts_dir = "~/.local/share/ctx/contexts"  # where checkouts live
+repos_dir = "~/.local/share/ctx/repos"        # internal storage for registered repos
+branch_prefix = ""                            # work branch prefix, e.g. "jane/"
+multiplexer = "tmux"                          # or "zellij" (requires zellij >= 0.44)
+
+# The pane layout: a tree of panes and "row"/"column" splits ("row" = side
+# by side, "column" = stacked). A pane runs `command` (default: a shell) in
+# the checkout; at most one pane may set `focus`.
+[layout]
+split = "row"
+
+[[layout.panes]]
+split = "column"
+[[layout.panes.panes]]
+command = "lazygit"
+[[layout.panes.panes]]
+command = "nvim"
+
+[[layout.panes]]
+command = "claude"
+focus = true
+```
+
+### Environment variables
+
+Fresh checkouts don't carry untracked files like `.env`. All contexts of a
+repo share the parent directory `<contexts_dir>/<repo>/`; you could, for
+example, use a tool like [direnv](https://direnv.net) to export env vars in
+all of a repo's contexts from a single `.envrc` there:
+
+```sh
+echo 'export MY_SECRET=some-value' > <contexts_dir>/papaya-nvim/.envrc
+direnv allow <contexts_dir>/papaya-nvim
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).

ctx_tui-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "ctx-tui"
+version = "0.1.0"
+description = "Manage repo-scoped work contexts: fresh checkouts wrapped in terminal multiplexer sessions"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.13"
+dependencies = [
+    "click>=8.1",
+    "textual>=8.2.8",
+]
+
+[project.scripts]
+ctx = "ctx.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.7,<0.9"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "ctx"
+
+[dependency-groups]
+dev = [
+    "mypy>=2.3.0",
+    "ruff>=0.16.0",
+]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # bugbear
+    "SIM", # simplify
+    "PTH", # pathlib
+    "RUF",
+]
+
+[tool.mypy]
+strict = true

ctx_tui-0.1.0/src/ctx/cli.py

@@ -0,0 +1,206 @@
+import subprocess
+import sys
+
+import click
+
+from ctx import contexts, repos
+from ctx.config import Config, ConfigError, load_config
+from ctx.layout import LayoutError
+from ctx.multiplexer import Multiplexer, MultiplexerError, get_multiplexer
+
+
+@click.group(invoke_without_command=True)
+@click.version_option(package_name="ctx-tui")
+@click.pass_context
+def cli(click_ctx: click.Context) -> None:
+    """Manage repo-scoped work contexts."""
+    if click_ctx.invoked_subcommand is None:
+        click_ctx.invoke(tui)
+
+
+@cli.command()
+@click.argument("repo")
+@click.argument("name")
+@click.option("-b", "--branch", "base", help="Base branch (default: the repo's default branch).")
+def new(repo: str, name: str, base: str | None) -> None:
+    """Create a context: fresh checkout of REPO on a new local branch."""
+    _create_and_open(load_config(), repo, name, base)
+
+
+def _create_and_open(cfg: Config, repo: str, name: str, base: str | None) -> None:
+    try:
+        ctx = contexts.create_context(cfg, repo, name, base)
+    except (FileExistsError, FileNotFoundError) as exc:
+        raise click.ClickException(str(exc)) from exc
+    click.echo(f"created {ctx.qualified} at {ctx.path} on {contexts.current_branch(ctx)}")
+    try:
+        get_multiplexer(cfg.multiplexer, cfg.layout).open(ctx)
+    except MultiplexerError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+@cli.command("open")
+@click.argument("name")
+def open_(name: str) -> None:
+    """Attach to a context's session, recreating it if needed."""
+    cfg = load_config()
+    try:
+        ctx = contexts.find_context(cfg, name)
+    except LookupError as exc:
+        raise click.ClickException(str(exc)) from exc
+    try:
+        get_multiplexer(cfg.multiplexer, cfg.layout).open(ctx)
+    except MultiplexerError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+@cli.command("list")
+def list_() -> None:
+    """List contexts with branch, dirtiness, and session state."""
+    cfg = load_config()
+    all_contexts = contexts.list_contexts(cfg)
+    if not all_contexts:
+        click.echo("no contexts")
+        return
+    rows = [("NAME", "REPO", "BRANCH", "STATUS")]
+    for ctx in all_contexts:
+        status = []
+        if contexts.is_dirty(ctx):
+            status.append("uncommitted changes")
+        unpushed = contexts.unpushed_commits(ctx)
+        if unpushed:
+            status.append(f"{len(unpushed)} unpushed commit(s)")
+        rows.append(
+            (
+                ctx.name,
+                ctx.repo,
+                contexts.current_branch(ctx),
+                ", ".join(status) or "clean",
+            )
+        )
+    widths = [max(len(row[column]) for row in rows) for column in range(len(rows[0]))]
+    for row in rows:
+        cells = zip(row, widths, strict=True)
+        click.echo("  ".join(cell.ljust(width) for cell, width in cells).rstrip())
+
+
+@cli.command()
+@click.argument("names", nargs=-1, required=True)
+@click.option("--force", is_flag=True, help="Delete even with uncommitted or unpushed work.")
+def rm(names: tuple[str, ...], force: bool) -> None:
+    """Delete contexts: kill their sessions and remove the checkouts."""
+    cfg = load_config()
+    mux = get_multiplexer(cfg.multiplexer, cfg.layout)
+    failed = False
+    for name in names:
+        error = _remove_one(cfg, mux, name, force)
+        if error:
+            click.echo(f"error: {error}", err=True)
+            failed = True
+    if failed:
+        sys.exit(1)
+
+
+def _remove_one(cfg: Config, mux: Multiplexer, name: str, force: bool) -> str | None:
+    """Delete one context, returning an error message instead of raising."""
+    try:
+        ctx = contexts.find_context(cfg, name)
+    except LookupError as exc:
+        return str(exc)
+    if not force:
+        problems = []
+        if contexts.is_dirty(ctx):
+            problems.append("uncommitted changes")
+        unpushed = contexts.unpushed_commits(ctx)
+        if unpushed:
+            problems.append(f"{len(unpushed)} unpushed commit(s)")
+        if problems:
+            return f"{ctx.qualified} has {' and '.join(problems)}; use --force to delete anyway"
+    if mux.exists(ctx):
+        mux.kill(ctx)
+    contexts.remove_context(ctx)
+    click.echo(f"removed {ctx.qualified}")
+    return None
+
+
+@cli.command()
+@click.option("--exit", "exit_on_open", is_flag=True, help="Exit the TUI after opening a context.")
+def tui(exit_on_open: bool) -> None:
+    """Manage contexts and repos interactively."""
+    from ctx.tui import CtxTui, NewRequest, OpenRequest
+
+    cfg = load_config()
+    mux = get_multiplexer(cfg.multiplexer, cfg.layout)
+    # When the multiplexer can open sessions in place (e.g. inside tmux),
+    # the TUI handles everything itself and exits with no request. The
+    # requests below are the fallback for terminal-takeover attaches.
+    match CtxTui(cfg, mux, exit_on_open=exit_on_open).run():
+        case OpenRequest(name=name):
+            try:
+                ctx = contexts.find_context(cfg, name)
+                mux.open(ctx)
+            except (LookupError, MultiplexerError) as exc:
+                raise click.ClickException(str(exc)) from exc
+        case NewRequest(repo=repo_name, name=name, base=base):
+            _create_and_open(cfg, repo_name, name, base)
+        case None:
+            pass
+
+
+@cli.group()
+def repo() -> None:
+    """Manage registered repositories."""
+
+
+@repo.command("add")
+@click.argument("url")
+@click.option("--name", help="Registry name (default: derived from URL).")
+def repo_add(url: str, name: str | None) -> None:
+    """Register a repository by cloning a local bare mirror of it."""
+    cfg = load_config()
+    try:
+        registered = repos.add_repo(cfg, url, name)
+    except FileExistsError as exc:
+        raise click.ClickException(str(exc)) from exc
+    click.echo(f"registered '{registered}'")
+
+
+@repo.command("list")
+def repo_list() -> None:
+    """List registered repositories."""
+    cfg = load_config()
+    for name in repos.repo_names(cfg):
+        click.echo(f"{name}\t{repos.repo_url(cfg, name)}")
+
+
+@repo.command("rm")
+@click.argument("names", nargs=-1, required=True)
+def repo_rm(names: tuple[str, ...]) -> None:
+    """Remove registered repositories' mirrors (contexts are untouched)."""
+    cfg = load_config()
+    failed = False
+    for name in names:
+        try:
+            repos.remove_repo(cfg, name)
+        except FileNotFoundError as exc:
+            click.echo(f"error: {exc}", err=True)
+            failed = True
+            continue
+        click.echo(f"removed '{name}'")
+    if failed:
+        sys.exit(1)
+
+
+def main() -> None:
+    try:
+        cli()
+    except subprocess.CalledProcessError as exc:
+        cmd = " ".join(map(str, exc.cmd))
+        click.echo(f"error: command failed ({cmd})", err=True)
+        sys.exit(exc.returncode or 1)
+    except LayoutError as exc:
+        click.echo(f"error: invalid layout: {exc}", err=True)
+        sys.exit(1)
+    except ConfigError as exc:
+        click.echo(f"error: invalid config: {exc}", err=True)
+        sys.exit(1)

ctx_tui-0.1.0/src/ctx/config.py

@@ -0,0 +1,53 @@
+import os
+import tomllib
+from dataclasses import dataclass, replace
+from pathlib import Path
+
+from ctx.layout import DEFAULT_LAYOUT, Node, parse_layout
+from ctx.multiplexer import MultiplexerKind
+
+
+def _xdg_dir(variable: str, fallback: Path) -> Path:
+    value = os.environ.get(variable, "")
+    return Path(value) if value else Path.home() / fallback
+
+
+CONFIG_PATH = _xdg_dir("XDG_CONFIG_HOME", Path(".config")) / "ctx" / "config.toml"
+_DATA_DIR = _xdg_dir("XDG_DATA_HOME", Path(".local") / "share") / "ctx"
+
+
+class ConfigError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class Config:
+    contexts_dir: Path = _DATA_DIR / "contexts"
+    repos_dir: Path = _DATA_DIR / "repos"
+    branch_prefix: str = ""
+    multiplexer: MultiplexerKind = MultiplexerKind.TMUX
+    layout: Node = DEFAULT_LAYOUT
+
+
+def load_config() -> Config:
+    if not CONFIG_PATH.exists():
+        return Config()
+    data = tomllib.loads(CONFIG_PATH.read_text())
+    cfg = Config()
+    if "contexts_dir" in data:
+        cfg = replace(cfg, contexts_dir=Path(data["contexts_dir"]).expanduser())
+    if "repos_dir" in data:
+        cfg = replace(cfg, repos_dir=Path(data["repos_dir"]).expanduser())
+    if "branch_prefix" in data:
+        cfg = replace(cfg, branch_prefix=str(data["branch_prefix"]))
+    if "multiplexer" in data:
+        raw = str(data["multiplexer"])
+        try:
+            kind = MultiplexerKind(raw)
+        except ValueError as exc:
+            valid = ", ".join(k.value for k in MultiplexerKind)
+            raise ConfigError(f"unknown multiplexer '{raw}' (supported: {valid})") from exc
+        cfg = replace(cfg, multiplexer=kind)
+    if "layout" in data:
+        cfg = replace(cfg, layout=parse_layout(data["layout"]))
+    return cfg

ctx_tui-0.1.0/src/ctx/contexts.py

@@ -0,0 +1,91 @@
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from ctx import repos
+from ctx.config import Config
+from ctx.git import git
+
+
+@dataclass(frozen=True)
+class Context:
+    repo: str
+    name: str
+    path: Path
+
+    @property
+    def qualified(self) -> str:
+        return f"{self.repo}/{self.name}"
+
+
+def context_path(cfg: Config, repo: str, name: str) -> Path:
+    return cfg.contexts_dir / repo / name
+
+
+def list_contexts(cfg: Config) -> list[Context]:
+    if not cfg.contexts_dir.is_dir():
+        return []
+    found = []
+    for repo_dir in sorted(cfg.contexts_dir.iterdir()):
+        if not repo_dir.is_dir():
+            continue
+        for ctx_dir in sorted(repo_dir.iterdir()):
+            if (ctx_dir / ".git").exists():
+                found.append(Context(repo_dir.name, ctx_dir.name, ctx_dir))
+    return found
+
+
+def find_context(cfg: Config, name: str) -> Context:
+    """Resolve a context name; names are globally unique."""
+    matches = [c for c in list_contexts(cfg) if c.name == name]
+    if not matches:
+        raise LookupError(f"no context '{name}'")
+    return matches[0]
+
+
+def create_context(cfg: Config, repo: str, name: str, base: str | None = None) -> Context:
+    mirror = repos.repo_path(cfg, repo)
+    if not mirror.exists():
+        raise FileNotFoundError(f"repo '{repo}' is not registered (ctx repo add <url>)")
+    taken = next((c for c in list_contexts(cfg) if c.name == name), None)
+    if taken is not None:
+        raise FileExistsError(f"context name '{name}' is already used by {taken.qualified}")
+    path = context_path(cfg, repo, name)
+
+    if base is None:
+        repos.update_repo(cfg, repo)
+        base = repos.default_branch(cfg, repo)
+        fetch_base = False
+    else:
+        # The mirror only carries the default branch; fetch the base into the context.
+        fetch_base = True
+    path.parent.mkdir(parents=True, exist_ok=True)
+    git("clone", str(mirror), str(path))
+    git("remote", "set-url", "origin", repos.repo_url(cfg, repo), cwd=path)
+    if fetch_base:
+        try:
+            git("fetch", "origin", base, cwd=path)
+        except subprocess.CalledProcessError as exc:
+            remove_context(Context(repo, name, path))
+            raise FileNotFoundError(f"branch '{base}' not found on origin of '{repo}'") from exc
+    branch = f"{cfg.branch_prefix}{name}"
+    git("checkout", "--no-track", "-b", branch, f"origin/{base}", cwd=path)
+    return Context(repo, name, path)
+
+
+def current_branch(ctx: Context) -> str:
+    return git("branch", "--show-current", cwd=ctx.path)
+
+
+def is_dirty(ctx: Context) -> bool:
+    return bool(git("status", "--porcelain", cwd=ctx.path))
+
+
+def unpushed_commits(ctx: Context) -> list[str]:
+    out = git("log", "--branches", "--not", "--remotes", "--oneline", cwd=ctx.path)
+    return out.splitlines() if out else []
+
+
+def remove_context(ctx: Context) -> None:
+    shutil.rmtree(ctx.path)

ctx_tui-0.1.0/src/ctx/git.py

@@ -0,0 +1,8 @@
+import subprocess
+from pathlib import Path
+
+
+def git(*args: str, cwd: Path | None = None) -> str:
+    """Run git, letting stderr (progress, errors) stream to the terminal."""
+    result = subprocess.run(["git", *args], cwd=cwd, check=True, stdout=subprocess.PIPE, text=True)
+    return result.stdout.strip()