twin

twin is a cross-platform command-line tool that eliminates terminal navigation and multitasking friction. It allows you to instantly spawn parallel terminal windows or tabs that inherit the current shell's working directory, environment variables, and command history, and supports smart sibling-directory traversal.

Features

• Clone Terminal Session: Instantly launch a parallel terminal tab or window in the exact same directory, inheriting active environment variables.
• Smart Sibling Navigation (twin to): Walk up the directory tree to find a common root containing both the current directory and the target directory (e.g., jumping from project/backend/src/controllers/ to project/frontend/). Falls back to standard relative/absolute path checks.
• Context Inheritance: Inherits shell state including command history hints (last 10 commands) and custom environment variables.
• Cross-Platform Support: Built for Windows (Windows Terminal/PowerShell/CMD), macOS (Terminal.app/iTerm2), and Linux (Gnome Terminal, Konsole, xfce4-terminal, etc.).

Installation

Prerequisites

• Go (1.21 or later)

Building from Source

1. Clone this repository:

   git clone https://github.com/sudoaanish/twin.git
   cd twin

2. Build the binary:

   go build -o twin

3. Move the compiled binary (twin or twin.exe) to a directory in your system's PATH.

---

Configuration

twin utilizes a dual-layer architecture consisting of a lightweight shell wrapper and the compiled Go binary. You must load the shell wrapper in your shell profile to capture environment variables and history hints.

PowerShell

Add the following line to your profile script (e.g., Microsoft.PowerShell_profile.ps1):

twin init powershell | Out-String | Invoke-Expression

Zsh

Add the following line to your ~/.zshrc:

eval "$(twin init zsh)"

Bash

Add the following line to your ~/.bashrc:

eval "$(twin init bash)"

---

Usage

1. Clone Current Terminal

To spawn a parallel tab or window in the same directory, run:

twin

2. Navigate to Sibling Directory

To spawn a parallel terminal in a sibling directory (e.g., moving from project/backend/src/controllers/ to project/frontend/), run:

twin to frontend

If a sibling match is not found in the path hierarchy, twin falls back to checking if the path is a standard relative or absolute path.

---

Architecture

Because a compiled binary runs in its own isolated sub-process, it cannot natively modify the parent shell's directory or scrape local unexported variables. twin uses a dual-layer design:

1. Shell Wrappers/Hooks: A lightweight shell function wrapper captures the active PWD, active shell type, recently executed history commands, and custom (unexported) shell variables. It base64-encodes this context and passes it via process environment variables to the Go binary.
2. Go Binary: Decodes the context, runs the upward path traversal algorithm for sibling-directory queries, and invokes OS-specific terminal-spawning APIs (such as AppleScript on macOS, Process APIs with environment propagation on Windows, and terminal execution args on Linux).

License

This project is licensed under the MIT License.

Developed by Aanish Farrukh.