{"id":30367120,"url":"https://github.com/codethread/ksm","last_synced_at":"2025-10-08T12:40:10.250Z","repository":{"id":307342868,"uuid":"1027481876","full_name":"codethread/ksm","owner":"codethread","description":"kitty session manager","archived":false,"fork":false,"pushed_at":"2025-09-26T19:44:11.000Z","size":291,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-04T14:04:40.933Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codethread.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-07-28T04:48:20.000Z","updated_at":"2025-09-26T19:44:15.000Z","dependencies_parsed_at":"2025-07-30T20:25:16.530Z","dependency_job_id":"b88fe1c0-4cf6-4359-81f6-d71810feed7c","html_url":"https://github.com/codethread/ksm","commit_stats":null,"previous_names":["codethread/ksm"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/codethread/ksm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codethread%2Fksm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codethread%2Fksm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codethread%2Fksm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codethread%2Fksm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codethread","download_url":"https://codeload.github.com/codethread/ksm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codethread%2Fksm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278947686,"owners_count":26073728,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-19T23:13:32.580Z","updated_at":"2025-10-08T12:40:10.245Z","avatar_url":"https://github.com/codethread.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ksm (kitty session manager)\n\nA Rust based Kitty Session Manager to emulate tmux style project sessions within the Kitty terminal emulator.\n\n## Overview\n\nksm allows you to quickly switch between project directories by creating and managing Kitty tabs with project-specific environments. It supports both keyed shortcuts and interactive project selection.\n\n## Features\n\n- **Key-based switching**: Jump to projects using predefined keys\n- **Interactive selection**: Browse and select projects with fuzzy finding\n- **Session management**: Automatically create or focus existing project tabs\n- **Session-aware tab navigation**: Navigate between tabs within the current session context\n- **Work/Personal contexts**: Separate project sets for different contexts\n- **Project discovery**: Automatically find projects in configured directories\n\n## Installation\n\n```bash\n# Install from source\ncargo install --path ksm-cli\n\n# Or use the justfile\njust install\n\n# Then\nksm --help\n```\n\n## Configuration\n\n\u003e [!INFO]\n\u003e The `KSM_WORK` env (when set to a truthy value) enables the work context for all commands.\n\nCreate a configuration file at `~/.local/data/sessions.json`:\n\n```json\n{\n  \"dirs\": [\"~/dev/projects/*\", \"~/work/*/projects\", \"~/personal/code\", \"~/code/**/*-project\"],\n  \"base\": [\n    [\"config\", \"~/.config\"],\n    [\"dots\", \"~/dotfiles\"]\n  ],\n  \"personal\": [\n    [\"blog\", \"~/personal/blog\"],\n    [\"hobby\", \"~/personal/hobby-project\"]\n  ],\n  \"work\": [\n    [\"api\", \"~/work/main-api\"],\n    [\"frontend\", \"~/work/frontend-app\"]\n  ]\n}\n```\n\n### Configuration Structure\n\n- **`dirs`**: Array of directory patterns to scan for projects (supports glob patterns)\n  - **`~/dev/projects/*`**: Match all direct subdirectories in `~/dev/projects` (e.g., `~/dev/projects/project1`, `~/dev/projects/project2`)\n  - **`~/work/*/projects`**: Match directories named `projects` in any subdirectory of `~/work` (e.g., `~/work/team1/projects`, `~/work/team2/projects`)\n  - **`~/personal/code`**: Literal directory path (no glob expansion)\n  - **`~/code/**/\\*-project`**: Match any directory ending in `-project`at any depth under`~/code` using recursive glob\n- **`base`**: Key-value pairs available in both work and personal contexts\n- **`personal`**: Key-value pairs available only in personal context\n- **`work`**: Key-value pairs available only in work context\n\n#### Glob Pattern Support\n\nThe `dirs` configuration supports standard glob patterns:\n\n- **`*`**: Matches any number of characters within a directory name (non-recursive)\n- **`**`\\*\\*: Matches any number of directories recursively\n- **`?`**: Matches exactly one character\n- **`[abc]`**: Matches any one character in the set\n- **`[!abc]`**: Matches any one character not in the set\n\n**Examples:**\n\n- `~/projects/*` → `~/projects/web-app`, `~/projects/api-service`\n- `~/code/**/*.git` → Any `.git` directory at any depth under `~/code`\n- `~/work/team[12]/src` → `~/work/team1/src`, `~/work/team2/src`\n- `~/dev/project-*` → `~/dev/project-alpha`, `~/dev/project-beta`\n\nEach project entry is a `[key, path]` pair where:\n\n- `key`: Short identifier for quick access\n- `path`: Full or tilde-expanded path to the project directory\n\n## Usage\n\n### Basic Commands\n\n```bash\n# Jump to a project by key\nksm key \u003cproject-key\u003e\n\n# Interactive project selection\nksm select\n\n# List all available projects\nksm list\n\n# Rename current tab (preserves session context)\nksm rename-tab \"Development Environment\"\n```\n\n### Session-Aware Tab Navigation\n\nNavigate between tabs within your current session context:\n\n```bash\n# Navigate to next tab in current session\nksm next-tab\n\n# Navigate to previous tab in current session\nksm prev-tab\n\n# Navigate without wrap-around (stops at first/last tab)\nksm next-tab --no-wrap\nksm prev-tab --no-wrap\n```\n\n#### How Session Navigation Works\n\n- **Session Context**: When you create a project session with `ksm key` or `ksm select`, tabs are automatically tagged with the session context\n- **Session-Aware Navigation**: The `next-tab`/`prev-tab` commands only cycle through tabs belonging to your current session\n- **Automatic Inheritance**: New tabs created from within a session automatically inherit the session context\n- **Unnamed Sessions**: Tabs created outside of any session are grouped into an \"unnamed\" session\n- **Wrap-Around**: By default, navigation wraps around (last tab → first tab), but can be disabled with `--no-wrap`\n\nThis allows you to efficiently navigate between tabs relevant to your current project without cycling through unrelated tabs.\n\n#### Session Identification\n\nKSM uses a robust dual-approach for identifying sessions:\n\n1. **Tab Titles** (Primary): Sessions are marked with a `session:\u003cname\u003e` prefix in tab titles, which persists even when windows within a tab are closed\n2. **Environment Variables** (Fallback): Uses `KITTY_SESSION_PROJECT` for backward compatibility with existing sessions\n\nThe `rename-tab` command allows you to customize tab descriptions while preserving the session marker:\n\n```bash\n# In a session named \"myproject\"\nksm rename-tab \"API Development\"\n# Tab title becomes: \"session:myproject - API Development\"\n\n# Outside of any session\nksm rename-tab \"Personal Tasks\"\n# Tab title becomes: \"Personal Tasks\"\n```\n\n### Recommended Kitty Configuration\n\nTo prevent Kitty from automatically overwriting session titles, add this to your `~/.config/kitty/kitty.conf`:\n\n```bash\n# Preserve custom tab titles (including session markers)\nshell_integration no-title\n```\n\n## Development\n\nThis project uses a Rust workspace with two main packages:\n\n- **`ksm-cli`**: The main CLI application\n- **`kitty-lib`**: Rust abstraction over Kitty terminal apis\n\nSee the justfile for available development commands:\n\n```bash\njust --list     # Show all available commands\njust ci         # Run comprehensive checks (format, lint, test)\njust test       # Run all tests\njust lint       # Run clippy linter\njust fmt        # Format code\n```\n\nSee individual package READMEs for more details:\n\n- [ksm-cli/README.md](ksm-cli/README.md) - CLI development guide\n- [kitty-lib/README.md](kitty-lib/README.md) - Library architecture and API\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodethread%2Fksm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodethread%2Fksm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodethread%2Fksm/lists"}