sesh

A bash-inspired shell for prompting, summarizing, and steering your AI coding sessions. sesh borrows its vocabulary from real shell/git tools you already know — history, jobs, log — and repoints them at the question "what is happening in this project and what do I do next?"

Every command is a well-behaved unix filter: it reads context off disk (git, CLAUDE.md, TODO.md, a sessions/ log directory), assembles a prompt or a concrete command list, and writes plain text to stdout. Composition is just the real shell — no custom pipe parser, no DSL to learn.

sesh goal | sesh plan -x
sesh log --all > session-history.md
sesh audit --prompt | sesh plan -x

Install

npm i -g @neuralq/sesh

The command is sesh. Requires Node.js >=18.

Or from source:

git clone https://github.com/shivank-codes/sesh.git
cd sesh
npm link   # exposes the `sesh` binary globally

No dependencies — it's plain Node.js, so either path is instant.

Commands

| Command | Bash/git analog | Answers | |---|---|---| | sesh goal | pwd | What is the current goal we're working toward? | | sesh history [--open] | history | What tasks are done (or still open)? | | sesh jobs [--all] | jobs | What's active right now — optionally across every session on record? | | sesh log [--all] [--session <id>] | git log | Summary of the current session, or of every session. | | sesh plan | — | What are the next 3-5 concrete steps? | | sesh test [unit\|integration\|load\|all] | make test | Concrete test commands for the stack this repo actually uses. | | sesh audit [--prompt] | — | Vulnerability-scan commands for this stack, or an LLM security-review prompt. | | sesh run <file.sesh> | bash script.sh | Run a script that chains sesh/shell commands. |

Aliases for muscle memory: tasks/status → jobs, summary → log.

Options

• -x, --exec — send the assembled prompt to the configured LLM (Anthropic) and print the reply, instead of just printing the prompt. Requires ANTHROPIC_API_KEY. Without it, sesh is a pure prompt generator: pipe its output into whatever LLM CLI or chat UI you like.
• SESH_MODEL — override the model used with -x (defaults to claude-sonnet-5).

How it finds context

• Git: last 15 commits, working tree status, current branch.
• Docs: CLAUDE.md and README.md in the repo root.
• Tasks: a TODO.md (or docs/TODO.md) markdown checklist — - [ ] / - [x] items become open/done tasks.
• Sessions: a sessions/ directory (or .sesh/sessions/, docs/sessions/) of .md/.txt files, one per session, newest first by mtime. This repo's own sessions/ and TODO.md are sample data — replace them with your project's.
• Stack (for test/audit): presence of package.json, requirements.txt/pyproject.toml, pom.xml, build.gradle(.kts), go.mod, or Cargo.toml.

None of this requires an API key — goal, log, plan, and audit --prompt work offline as prompt generators; test and audit work offline as command generators.

Example: a daily standup script

sesh run examples/daily-standup.sesh

See examples/daily-standup.sesh — a .sesh file is just a shell script by convention, so it gets set -e, &&, |, and everything else bash already gives you for free.

Design principles

1. Command names are borrowed, not invented. If bash or git already has a word for the concept, reuse it (history, jobs, log).
2. Composability comes from the OS, not from sesh. Each command is stdin in, stdout out — real pipes and redirects just work.
3. Offline-first. Every command has a useful offline mode (print the prompt, print the commands); -x is opt-in.
4. No framework lock-in. Zero runtime dependencies, plain Node.js.

Contributing

Issues and PRs welcome. The whole implementation is ~10 small files under src/ — src/context.js gathers repo context, src/promptTemplates.js turns context into prompts, src/commands/*.js are the command handlers. Add a new command by dropping a file in src/commands/ and registering it in bin/sesh.js.

License

MIT — see LICENSE.