{"id":26538621,"url":"https://github.com/henriquedoval/shellserver","last_synced_at":"2026-02-21T10:01:18.519Z","repository":{"id":64038291,"uuid":"560687348","full_name":"HenriquedoVal/shellserver","owner":"HenriquedoVal","description":"Server to aid in shell navigation.","archived":false,"fork":false,"pushed_at":"2024-04-03T04:20:21.000Z","size":3706,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-27T20:13:02.736Z","etag":null,"topics":["powershell","prompt","terminal","windows"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HenriquedoVal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-11-02T03:13:16.000Z","updated_at":"2023-05-22T09:24:31.000Z","dependencies_parsed_at":"2023-02-13T18:35:50.465Z","dependency_job_id":null,"html_url":"https://github.com/HenriquedoVal/shellserver","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/HenriquedoVal/shellserver","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HenriquedoVal%2Fshellserver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HenriquedoVal%2Fshellserver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HenriquedoVal%2Fshellserver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HenriquedoVal%2Fshellserver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HenriquedoVal","download_url":"https://codeload.github.com/HenriquedoVal/shellserver/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HenriquedoVal%2Fshellserver/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29679049,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T09:33:50.764Z","status":"ssl_error","status_checked_at":"2026-02-21T09:33:19.949Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["powershell","prompt","terminal","windows"],"created_at":"2025-03-21T23:18:52.472Z","updated_at":"2026-02-21T10:01:18.497Z","avatar_url":"https://github.com/HenriquedoVal.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ShellServer\n\nIt's a mix of [Starship](https://github.com/starship/starship) and [Zoxide](https://github.com/ajeetdsouza/zoxide) made to be faster on Windows.  \n  \nThe common approach of piping binaries outputs is almost free on\nLinux but this is not true on Windows, the cost of raising processes is\nway higher and long living processes are preferred.  \n\nOn Starship, every 'Enter' keystroke spawns a new process, which may cause a lag between prompts.  \nZoxide will raise a new process every time you call it.  \nShellServer raises the server only in the first shell creation and will _communicate_ with your shell on every 'Enter' keystroke.  \n  \nBut if your hardware gives you a fluid shell experience using Starship, I recommend that you keep with it because it's way more customizable.  \n\n## Features\n  \n### Prompt with a fast glance at what is in the directory  \n\n![Bloated](./images/bloated.png)  \nThis is a sample of the prompt that you will get.\nIt will indicate the existence of Python, C, C++, C#, Lua, Node, PowerShell, Rust, and Java files in the directory.  \nThe C compilers searched are GCC and G++.  \n  \n### No lag from spawning processes  \n\n![Fast](./images/even_bloated.gif)  \n  \n### Better 'cd'  \n\n![p, pz](./images/p_pz.gif)\n\u003cdetails\u003e\n\u003csummary\u003eOptions\u003c/summary\u003e\n\n- `p path -o`: For writing to output. Tool for things like `move somefile (p -o somepath)`.\n- `p path -j`: Go to the Junction of the given `path`\n- `p -d path`: Purges given relative or full paths from known paths.\n- `p -dr refpath`: Deletes only the given `refpath` from known paths.\n- `p -a path`: Manually add given `path` to tracked dirs.\n- `p -a path -as given_name`: Will use `given_name` to jump to `path`.\n- `p` behaves like `cd` for relative paths.  \nInvocations like `p -d . -dr someref -a . -as anyname anyref -j -o` are allowed, but doesn't make much sense.  \nIt would remove all references to the current dir, delete `someref`, add the current dir as `anyname`, and write the junction\nof `anyref` to the output...\n\u003c/details\u003e\n  \n### Switching Theme\n  \n![Switch-Theme](./images/switch_theme.gif)\nThe name changed to `Switch-ShellServerTheme`.  \n\u003cdetails\u003e\n\u003csummary\u003eOptions\u003c/summary\u003e\n\nSwitches colors to conform with light/dark themes.  \nCan take five arguments: system, terminal, blue, prompt, and readline.  \n- system: Toggles system-wide Light/Dark Mode.  \n- terminal: Toggles Windows Terminal default theme.\n- blue: Toggles 'Blue light reduction'.  \n- prompt: Toggles prompt colors. \n- readline: Toggles PSReadLine colors. \n  \nThe `system` option is not working properly on Windows 11 22h2...\n\n\u003c/details\u003e\n  \n### Searching history\n\n![history](./images/history.gif)\nThe name changed to `Search-ShellServerHistory`.  \n\u003cdetails\u003e\n\u003csummary\u003eOptions\u003c/summary\u003e\n\nThe amount of data printed will be limited to fit the terminal.\n- pass `-a` to get the full result\n- `-c` to make the search case-sensitive\n- `-ac` and `-ca` are allowed too\n\u003c/details\u003e\n\n### Listing directory\n\n![lss](./images/ll_la.gif)  \n\n\u003cdetails\u003e\n\u003csummary\u003eOptions\u003c/summary\u003e\n\nThere are several switches. See `help ll`.\n`ll -List -Icons -Color` will use these options for the current execution.  \nAn additional `-SetDefault` will make your flags persist.  \nUse `-NoOutput` if you want to set it in $profile.  \n  \nMost flags can be aliased like:  \n`ll -l -ac -he`  \nOr prepending `-o` plus the initial of the flag:  \n`ll -o acilmhCAH`  \n  \nMeaning:  \na: all files  \nc: colors  \ni: icons  \nl: list  \nm: modified time  \nh: headers  \nC: creation time  \nA: access time  \nH: hour  \n\n\u003c/details\u003e\n\n### Plugins\n\nAll those are relative to getting the git status.\n\n- [watchdog](https://github.com/gorakhargosh/watchdog): Filesystem watcher. Makes better caching possible.\n- [pygit2](https://github.com/libgit2/pygit2): libgit2 python bindings. Faster than using git itself.\n- [ssd_checker](https://github.com/kipodd/ssd_checker): Solid-State Drive checker. Change the strategy accordingly to drive speed.  \n  \nJust `pip install` the ones you want, restart shellserver, and no further config is needed.\n\n\n### Customization\n\nThe server will look for a `.shellserver.toml` in the user home directory.  \nThe most important option will be `git_timeout`.\n\n~~~toml\ngit_timeout = 500  # in ms, defaults to 2500\n# The best value is hardware-dependent.\n# If you have watchdog, I would recommend something around 100,\n# if you don't and the value is too low you might get no status over and over: `[...]`\n~~~\nSee the [example](./.shellserver.toml) for more and the defaults.\n  \n## CLI\n\nThe server knows how many clients it has and will know if you quit the shell with 'exit'  \nbut if the window or tab is closed on the 'X' button it may outlive the shell. \n\n~~~\nusage: shellserver \u003cCOMMAND\u003e [Args]\n       shellserver {kill|sync|clear|dump}\n       shellserver run [Args]\n\nshellserver gives some functionalities for better navigation on PowerShell\n\ncommands:\n\n    run       Run the server.\n    kill      Kill the server.\n    sync      Clear useless entries and write cache to disk.\n    clear     Delete the server cache.\n    dump      Dump the server cache to stdout.\n\noptions:\n  -h, --help  show this help message and exit\n~~~\n\n## Requirements\n\n- Python 3.10+ (CPython 3.11+ recommended)\n- PowerShell 7.4.1+\n- Any NerdFont (I use MesloLGS NF [patched](https://github.com/romkatv/powerlevel10k/blob/master/font.md))\n- A xterm compatible terminal\n\n## Installation\n\nShellServer will work only in PowerShell on Windows.\n\n~~~PowerShell\n\u003e pip install shellserver  # or pip install --user shellserver\n\u003e Install-Module ShellServer -Scope CurrentUser -AllowClobber\n~~~\n\n### Setup the server\n\nThere is a [helper script](./on_startup.ps1) to set the server to run on startup.\nAlternatively, you can start the server manually with:\n- `shellserverw run`: Does not create output terminal\n- `shellserver run`\n  \n### Setup the client\n\nAdd `Import-Module ShellServer` by the end of your PowerShell profile.  \n\n### Keep updated\n\nAs many things might change in versions below 0.1.0, consider upgrading both when one changes.\n~~~PowerShell\n\u003e shellserver kill\n\u003e Remove-Module ShellServer\n\n\u003e pip install --upgrade shellserver\n\u003e Update-Module ShellServer\n\n\u003e Start-ScheduledTask ShellServer\n\u003e Import-Module ShellServer\n~~~\nLast break: Client (PowerShell module) v0.1.1 and Server (Python) v0.0.18.\n\n## Debugging\n\nAll initial '--' are optional.  \nThe git status info is still experimental, do `pythonw -m shellserver --use-git` in your profile to always use git. \nIf you have installed pygit2, you can pass `--use-pygit2` instead, which is faster than `--use-git`.  \n\nAny errors that occur will be saved in `$env:localappdata\\shellserver\\traceback`.  \n  \nAttach a _stdout_ to the server, pass `--timeit` to it and it will give the time taken for each communication.  \nUse `output=stdout` to get some info on the git repo. You can pass `output=C:\\path\\to\\file` too.  \n~~~\n\u003e shellserver kill\n# A message that the server is not responding and your prompt will be like before.\n\u003e python -m shellserver --timeit --output=stdout  # no w, blocking\n~~~\nOpen another shell and walk to a git repo.  \n  \nThere are also: \n- --no-fallback: We will use our 'gitstatus' subpackage for repos up to 2500 index entries (in ssd, 1000 otherwise if ssd_checker is present). Will use git otherwise, unless this flag is set.\n- --no-watchdog: Disables Watchdog plugin\n- --disable-git\n- --use-git  # instead of gitstatus subpackage\n- --use-pygit2\n- --linear: Fill gitstatus info synchronously\n- --multiproc: Very beta and will not be updated\n- --no-read-async\n- --let-crash: At this point, it's probably useless\n- --test-status: Put gitstatus subpackage result and git.exe status side-by-side\n\nPwsh module cmdlets:\n\n- `Get-ShellServerConfig`: get the current server config.\n- `Get-ShellServerBuffer`: get output if it is set to 'buffer'. Pass `-k` to keep the content in memory.\n- `Switch-ShellServerTimeout`: arg in ms. \n- `Switch-ShellServerOptions`: Sets most of the argv options in runtime:\n    - use-git\n    - use-gitstatus: Use gitstatus subpackage for git status info\n    - use-pygit2\n    - disable-git\n    - enable-git\n    - timeit\n    - no-timeit\n    - fallback\n    - no-fallback\n    - watchdog\n    - no-watchdog\n    - test-status\n    - no-test-status\n    - linear\n    - no-linear\n    - read-async\n    - no-read-async\n    - let-crash\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhenriquedoval%2Fshellserver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhenriquedoval%2Fshellserver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhenriquedoval%2Fshellserver/lists"}