{"id":27915502,"url":"https://github.com/jlevy/kash","last_synced_at":"2025-12-14T15:02:59.292Z","repository":{"id":285780793,"uuid":"946350623","full_name":"jlevy/kash","owner":"jlevy","description":"The knowledge agent shell","archived":false,"fork":false,"pushed_at":"2025-04-30T00:25:24.000Z","size":1787,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-30T01:27:29.714Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://git.new/kash","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jlevy.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-11T02:13:43.000Z","updated_at":"2025-04-30T00:25:28.000Z","dependencies_parsed_at":null,"dependency_job_id":"8b4a2e92-a16b-4a43-a64d-70cda8d5962e","html_url":"https://github.com/jlevy/kash","commit_stats":null,"previous_names":["jlevy/kash","jlevy/kash-shell"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Fkash","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Fkash/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Fkash/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Fkash/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jlevy","download_url":"https://codeload.github.com/jlevy/kash/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252718032,"owners_count":21793424,"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","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-05-06T15:55:01.163Z","updated_at":"2025-10-30T00:16:20.220Z","avatar_url":"https://github.com/jlevy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg width=\"392\" alt=\"kash\"\nsrc=\"https://github.com/user-attachments/assets/a5d62ae4-17e6-46bb-a9cb-3b6ec8d8d3fe\" /\u003e\n\n\u003c/div\u003e\n\n\u003c/div\u003e\n\n## Hello!\n\nIf you’re seeing this, you there’s a good chance I shared it with you for feedback.\nThank you for checking out Kash.\n\nIt’s new, the result of some experimentation over the past few months.\nI like a lot of things about it but it isn’t mature and I’d love your help to make it\nmore usable. If you try it please **let me know** what works and what doesn’t work.\nOr if you just don’t get it, where you lost interest or got stuck.\nMy contact info is at [github.com/jlevy](https://github.com/jlevy) or [follow or DM\nme](https://x.com/ojoshe) (I’m fastest on Twitter DMs).\nThank you. :)\n\n## What is Kash?\n\n\u003e “*Simple should be simple.\n\u003e Complex should be possible.*” —Alan Kay\n\nKash (“Knowledge Agent SHell”) is an experiment in making software tasks more modular,\nexploratory, and flexible using Python and current AI tools.\n\nThe philosophy behind kash is similar to Unix shell tools: simple commands that can be\ncombined in flexible and powerful ways.\nIt operates on “items” such as URLs, files, or Markdown notes within a workspace\ndirectory.\n\nYou can use Kash as an **interactive, AI-native command-line** shell for practical\nknowledge tasks.\n\nBut it’s actually not just a shell, and you can skip the shell entirely.\nIt’s really simply **a Python library** that lets you convert a simple Python function\ninto “actions” that work in a clean way on plain files in a workspace.\nAn action is also an MCP tool, so it integrates with other tools like Anthropic Desktop\nor Cursor.\n\nSo basically, it gives a unified way to use the shell, Python functions, and MCP tools.\n\nIt’s new and still has some rough edges, but it’s now working well enough it is feeling\nquite powerful. It now serves as a replacement for my usual shell (previously bash or\nzsh). I use it routinely to remix, combine, and interactively explore and then gradually\nautomate complex tasks by composing AI tools, APIs, and libraries.\nAnd last but not least, the same framework lets me build other tools (like\n[textpress](https://github.com/jlevy/textpress)).\n\nAnd of course, kash can read its own functionality and enhance itself by writing new\nactions.\n\n### Kash Packages\n\nThe [kash-shell](https://github.com/jlevy/kash) package is the base package and includes\nthe Python framework, a few core utilities, and the Kash command-line shell.\n\nAdditional actions for handling more complex tasks like converting documents and\ntranscribing, researching, or annotating videos, are in the\n[kash-docs](https://github.com/jlevy/kash-docs) and\n[kash-media](https://github.com/jlevy/kash-media) packages, all available on PyPI and\nquick to install via uv.\n\n### Key Concepts\n\n- **Actions:** The core of Kash are **actions**. By decorating a Python function with\n  `@kash_action`, you can turn it into an action, which makes it more flexible and\n  powerful. It can then be used like a command line command as well as a Python function\n  or an MCP tool.\n\n- **Workspaces:** A key element of Kash is that it does most nontrivial work in the\n  context of a **workspace**. A workspace is just a directory of files that have a few\n  conventions to make it easier to maintain context and perform actions.\n  A bit like how Git repos work, it has a `.kash/` directory that holds metadata and\n  cached content. The rest can be anything, but is typically directories of content and\n  resources (often Markdown or HTML but also .docx or .pdf or links to web pages).\n  All text files use [frontmatter-format](https://github.com/jlevy/frontmatter-format)\n  so have YAML metadata that includes not just title or description, but also how it was\n  created. All Markdown files are auto-formatted with\n  [flowmark](https://github.com/jlevy/flowmark), which makes documents much easier to\n  diff and version control (and prettier to read and edit).\n\n- **Compositionality:** An action is composable with other actions simply as a Python\n  function, so complex operations (for example, transcribing and annotating a video and\n  publishing it on a website) actions can be built from simpler actions (say downloading\n  and caching a YouTube video, identifying the speakers in a transcript, formatting it\n  as pretty HTML, etc.). The goal is to reduce the “interstitial complexity” of\n  combining tools, so it’s easy for you (or an LLM!) to combine tools in flexible and\n  powerful ways.\n\n- **Command-line usage:** In addition to using the function in other libraries and\n  tools, an action is also **a command-line tool** (with auto-complete, help, etc.)\n  in the Kash shell. So you can simply run `transcribe` to download and transcribe a\n  video. In kash you have **smart tab completions**, **Python expressions**, and an **LLM\n  assistant** built into the shell.\n\n- **Support for any API:** Kash is tool agnostic and runs locally, on file inputs in\n  simple formats, so you own and manage your data and workspaces however you like.\n  You can use it with any models or APIs you like, and is already set up to use the APIs\n  of **OpenAI** (GPT-5 is now the default model), **Anthropic Claude**, **Google\n  Gemini**, **xAI Grok**, **Mistral**, **Groq (Llama, Qwen, Deepseek)** (via\n  **LiteLLM**), **Deepgram**, **Perplexity**, **Firecrawl**, **Exa**, and any Python\n  libraries. There is also some experimental support for **LlamaIndex** and **ChromaDB**.\n\n- **MCP support:** Finally, an action is also an **MCP tool server** so you can use it\n  in any MCP client, like Anthropic Desktop or Cursor.\n\n### What Can Kash Do?\n\nYou can use kash actions to do deep research, transcribe videos, summarize and organize\ntranscripts and notes, write blog posts, extract or visualize concepts, check citations,\nconvert notes to PDFs or beautifully formatted HTML, or perform numerous other\ncontent-related tasks possible by orchestrating AI tools in the right ways.\n\nAs I’ve been building kash over the past couple months, I found I’ve found it’s not only\nfaster to do complex things, but that it has also become replacement for my usual shell.\nIt’s the power-tool I want to use alongside Cursor and ChatGPT/Claude.\nWe all know and trust shells like bash, zsh, and fish, but now I find this is much more\npowerful for everyday usage.\nIt has little niceties, like you can just type `files` for a better listing of files or\n`show` and it will show you a file the right way, no matter what kind of file it is.\nYou can also type something like “? find md files” and press tab and it will list you I\nfind it is much more powerful for local usage than than bash/zsh/fish.\nIf you’re a command-line nerd, you might like it a lot.\n\nBut my hope is that with these enhancements, the shell is also far more friendly and\nusable by anyone reasonably technical, and does not feel so esoteric as a typical Unix\nshell.\n\nFinally, one more thing: Kash is also my way of experimenting with something else new: a\n**terminal GUI support** that adds GUI features terminal like clickable text, buttons,\ntooltips, and popovers in the terminal.\nI’ve separately built a new desktop terminal app, Kerm, which adds support for a simple\n“Kerm codes” protocol for such visual components, encoded as OSC codes then rendered in\nthe terminal. Because Kash supports these codes, as this develops you will get the\nvisuals of a web app layered on the flexibility of a text-based terminal.\n\n## Installation\n\n### Running the Kash Shell\n\nKash offers a shell environment based on [xonsh](https://xon.sh/) augmented with a bunch\nof enhanced commands and customizations.\nIf you’ve used a bash or Python shell before, it should be very intuitive.\n\nWithin the kash shell, you get a full environment with all actions and commands.\nYou also get intelligent auto-complete, a built-in assistant to help you perform tasks,\nand enhanced tab completion.\n\nThe shell is an easy way to use Kash actions, simply calling them like other shell\ncommands from the command line.\n\nBut remember that’s just one way to use actions; you can also use them directly in\nPython or from an MCP client.\n\n### Current Kash Packages\n\nThe base installation of kash is the `kash-shell` package.\nHowever, some use cases require additional libraries, like video downloading tools, PDF\nhandling, etc.\n\nTo keep kash dependencies more manageable, these additional utilities and actions are\npackaged additional “kits”.\n\nThe examples below use video transcription from YouTube as an example.\nTo start with more full examples, I suggest starting with the `kash-media` kit.\n\n### Installation Steps\n\nThese steps have mainly been tested on macOS but should work on other platforms.\nThese are for `kash-media` but you can use a `kash-shell` for a more basic setup.\n\n1. **Install uv and Python:**\n\n   Kash is easiest to use via [**uv**](https://docs.astral.sh/uv/), the new package\n   manager for Python. `uv` replaces traditional use of `pyenv`, `pipx`, `poetry`, `pip`,\n   etc. Installing `uv` also ensures you get a compatible version of Python.\n   See [uv’s docs](https://docs.astral.sh/uv/getting-started/installation/) for other\n   installation methods and platforms.\n   Usually you just want to run:\n   ```shell\n   curl -LsSf https://astral.sh/uv/install.sh | sh\n   ```\n\n2. **Install additional command-line tools:**\n\n   In addition to Python, it’s highly recommended to install a few other dependencies to\n   make more tools and commands work.\n   For macOS, you can again use brew:\n\n   ```shell\n   brew update\n   brew install libmagic ffmpeg ripgrep bat eza hexyl imagemagick zoxide\n   ```\n\n   For Ubuntu:\n\n   ```shell\n   sudo apt-get update\n   sudo apt-get install -y libgl1 ffmpeg libmagic-dev imagemagick bat ripgrep hexyl\n   # Or for more additional command-line tools, pixi is better on Ubuntu:\n   curl -fsSL https://pixi.sh/install.sh | sh\n   . ~/.bashrc\n   pixi global install ripgrep bat eza hexyl imagemagick zoxide\n   ```\n\n   For Windows or other platforms, see the uv instructions.\n\n   Kash auto-detects and uses `ripgrep` (for search), `bat` (for prettier file display),\n   `eza` (a much improved version of `ls`), `hexyl` (a much improved hex viewer),\n   `imagemagick` (for image display in modern terminals), `libmagic` (for file type\n   detection), `ffmpeg` (for audio and video conversions)\n\n3. **Install kash or a kash kit:**\n\n   For a more meaningful demo, use an enhanced version of kash that also has various\n   media tools (like yt-dlp and Deepgram support):\n\n   ```shell\n   uv tool install kash-media --upgrade --python=3.13\n   ```\n\n   Other versions of Python should work but 3.13 is recommended.\n   For a setup without the media tools, just install `kash-shell` instead.\n\n4. **Set up API keys:**\n\n   You will need API keys for all services you wish to use.\n   Configuring OpenAI, Anthropic, Groq (for Llama 3), and Deepgram (if you wish to do\n   transcriptions) are a good start.\n   But kash supports dozens of models\n   [via LiteLLM](https://docs.litellm.ai/docs/providers).\n\n   You can set these up now, or after you run kash (below):\n\n   ```shell\n   # Set up API secrets:\n   cp .env.template .env \n   # Now edit the .env file to add all desired API keys.\n   # You can also put .env in ~/.env if you want it to be usable in any directory.\n   ```\n\n   These keys should go in the `.env` file in your current work directory or a parent or\n   your home directory (recommended if you’ll be working in several directories, as with\n   a typical shell).\n\n5. **Run kash:**\n\n   ```shell\n   kash\n   ```\n\n   You should see a welcome message with all info about APIs and tools.\n\n   Use the `self_check` command to confirm which tools and API keys are working.\n\n   Use the `self_configure` command as a quick way to fill in additional values in your\n   .env file and to set workspace parameters on what LLMs to use by default.\n\n### Running Kash as an MCP Server\n\nYou can use kash from your MCP client (such as Anthropic Desktop or Cursor).\n\nYou do this by running the the `kash-mcp` binary to make kash actions available as MCP\ntools.\n\nFor Claude Desktop, my config looks like this:\n\n```json\n{\n  \"mcpServers\": {\n    \"kash\": {\n      \"command\": \"/Users/levy/.local/bin/kash-mcp\",\n      \"args\": [\"--proxy\"]\n    }\n  }\n}\n```\n\nIf you add the `--proxy` arg, it will run an MCP stdio server but connect to the MCP SSE\nserver you are running in the kash shell, by default at `localhost:4440`.\n\nThen if you run `start_mcp_server` from the shell, your client will connect to your\nshell, and you can actually use any “published” kash action as an MCP tool.\n\nThen you can for example ask your MCP client “can you transcribe this video?”\nand give it a URL, and it will be able to call the `transcribe` action as a tool.\n\nWhat is even better is that all the inputs and outputs are saved in the current kash\nworkspace, just as if you’d been running these commands yourself in the shell.\nThis way, you don’t lose context or any work, and can seamlessly switch between an MCP\nclient like Cursor, the shell, and any other tools to edit the inputs or outputs of\nactions in your workspace directory.\n\n### Running Kash From Source\n\nSee the `development.md` file in GitHub for building and using kash from source.\n\n## Getting Started\n\n### Use Tab Completion and Help!\n\nTab completion is your friend!\nJust press tab to get lists of commands and guidance on help from the LLM-based\nassistant.\n\nYou can also ask any question directly in the shell.\n\nType `help` for the full documentation.\n\n### An Example: Transcribing Videos\n\nThe simplest way to illustrate how to use kash is by example.\nYou can go through the commands below a few at a time, trying each one.\n\nThis is a “real” example that uses ffmpeg and a few other libraries.\nSo to get it to work you must install not just the main shell but the kash “media kit”\nwith extra dependencies.\nThis is discussed in [the installation instructions](#installation-steps).\nIf you don’t have these already installed, you can add these tools:\n\nThen run `kash` to start.\n\nFor each command below you can use tab completion (which shows information about each\ncommand or option) or run with `--help` to get more details.\n\n```shell\n# Check the help page for a full overview:\nhelp\n\n# Confirm kash is set up correctly with right tools:\ncheck_system_tools\n\n# The assistant is built into the shell, so you can just ask questions on the\n# command line. Note you can just press Space twice and it will insert the question\n# mark for you:\n? how do I get started with a new workspace\n\n# Set up a workspace to test things out (we'll use fitness as an example):\nworkspace fitness\n\n# A short transcription (use this one or pick any video on YouTube):\ntranscribe https://www.youtube.com/watch?v=KLSRg2s3SSY\n\n# Note there is a selection indicated.\n# We can then look at the selected item easily, because commands often\n# will just work on the selection automatically:\nshow\n\n# Now let's manipulate that transcription. Note we are using the outputs\n# of each previous command, which are auto-selected as input to each\n# subsequent command. You can always run `show` to see the last result.\n\n# Remove the speaker id \u003cspan\u003e tags from the transcript.\nstrip_html\nshow\n\n# Break the text into paragraphs. Note this is smart enough to \"filter\"\n# the diff so even if the LLM modifies the text, we only let it insert\n# newlines.\nbreak_into_paragraphs\nshow\n\n# Look at the paragraphs and (by following the `derived_from` relation\n# this doc up to find the original source) then infer the timestamps\n# and backfill them, inserting timestamped link to the YouTube video\n# at the end of each paragraph.\nbackfill_timestamps\nshow\n\n# How about we add some headings?\ninsert_section_headings\n\n# How about we compare what we just did with what there was there\n# previously? \ndiff\n\n# If you're wondering how that works, it is an example of a command\n# that looks at the selection history.\nselect --history\n\n# And add some summary bullets and a description:\nadd_summary_bullets\nadd_description\n\n# Note we are just using Markdown still but inserting \u003cdiv\u003e tags to\n# add needed structure.\nshow\n\n# Render it as a PDF:\ncreate_pdf\n\n# See the PDF.\nshow\n\n# Cool. But it would be nice to have some frame captures from the video.\n? are there any actions to get screen captures from the video\n\n# Oh yep, there is!\n# But we're going to want to run it on the previous doc, not the PDF.\n# Let's see what the files are so far.\nfiles\n\n# Note we could select the file like this before we run the next command\n# with `select \u003csome-file\u003e.doc.md`. But actually we can see the history\n# of items we've selected:\nselect --history\n\n# And just back up to the previous one.\nselect --previous\n\n# Look at it again. Yep, there should be timestamps in the text.\nshow\n\n# As a side note, not all actions work on all items. So we also have\n# a way to check preconditions to see what attributes a given item has.\n# Note that for this doc `has_timestamps` is true.\npreconditions\n\n# And there is a way to see what commands are compatible with the current\n# selection based on these preconditions.\nsuggest_actions\n\n# Okay let's try it. (If you're using a shell that supports kash well,\n# you can just click the command name!)\ninsert_frame_captures\n\n# Note the screen capture images go to the assets folder as assets.\nfiles\n\n# Let's look at that as a web page.\nshow_webpage\n\n# Note that works because unlike regular `show`, that command\n# runs actions to convert a pretty HTML format.\nshow_webpage --help\n\n# And you can actually how this works by looking at its source:\nshow_webpage --show_source\n\n# What if something isn't working right?\n# Sometimes we may want to browse more detailed system logs:\nlogs\n\n# Note transcription works with multiple speakers, thanks to Deepgram\n# diarization. \ntranscribe https://www.youtube.com/watch?v=_8djNYprRDI\nshow\n\n# We can create more advanced commands that combine sequences of actions.\n# This command does everything we just did above: transcribe, format,\n# include timestamps for each paragraph, etc.\ntranscribe_format --help\ntranscribe_format https://www.youtube.com/watch?v=_8djNYprRDI\n\n# Getting a little fancier, this one adds little paragraph annotations and\n# a nicer summary at the top:\ntranscribe_annotate https://www.youtube.com/watch?v=_8djNYprRDI\n\nshow_webpage\n```\n\nThis is only the beginning but should give a flavor for how you can use kash.\nWith more actions, you can then take a transcript like this and have actions to extract\nconcepts, look up more about them with Perplexity, and crawl and save all the resources.\nYou might then visualize all the concepts.\nAll of these steps are just actions.\n\n### Creating a New Workspace\n\nAlthough you don’t always need one, a *workspace* is very helpful for any real work in\nkash. It’s just a directory of files, plus a `.kash/` directory with various logs and\nmetadata.\n\nNote the `.kash/cache` directory contains all the downloaded videos and media you\ndownload, so it can get large.\nYou can delete these files if they take up too much space.\n\nNote the `.kash/cache` directory contains all the downloaded videos and media you\ndownload, so it can get large.\nYou can delete these files if they take up too much space.\n(See the `cache_list` and `clear_cache` commands.)\n\nPick a workspace that encompasses a project or topic, and it lets you keep things\norganized.\n\nType `workspace` any time to see the current workspace.\n\nBy default, when you are not using the shell inside a workspace directory, or when you\nrun kash the first time, it uses the default *global workspace*.\n\nOnce you create a workspace, you can `cd` into that workspace and that will become the\ncurrent workspace. (If you’re familiar with how the `git` command-line works in\nconjunction with the `.git/` directory, this behavior is very similar.)\n\nTo start a new workspace, run a command like\n\n```\nworkspace health\n```\n\nThis will create a workspace directory called `health` in the current directory.\nYou can run `cd health` or `workspace health` to switch to that directory and begin\nworking.\n\n### Essential Kash Commands\n\nKash has quite a few basic commands that are easier to use than usual shell commands.\nYou can always run `help` for a full list, or run any command with the `--help` option\nto see more about the command.\n\nA few of the most important commands for managing files and work are these:\n\n- `self_check` to check existing .env file and installed tools (like bat and ffmpeg)\n\n- `self_configure` to help you configure your .env files and LLM models\n\n- `files` lists files in one or more paths, with sorting, filtering, and grouping.\n\n- `show` lets you show any file you wish, or with no argument shows the first file in\n  the current selection.\n  It auto-detects whether to show the file in the console, the browser, or using a\n  native app (like Excel for a .xls file), but you can customize this with options (see\n  `--help`).\n\n- `show_webpage` formats Markdown or HTML documents as a nice web page and opens your\n  browser to view it.\n\n- `workspace` shows or selects or creates a new workspace.\n  Initially you work in the default global workspace (typically at `~/Kash/workspace`)\n  but for more real work you’ll want to create a workspace, which is a directory to hold\n  the files you are working with.\n\n- `select` shows or sets selections, which are the set of files the next command will\n  run on, within the current workspace.\n\n- `edit` runs the currently configured editor (based on the `EDITOR` environment\n  variable) on any file, or the current selection.\n\n- `param` lets you set certain common parameters, such as what LLM to use (if you wish\n  to use non-default model or language).\n\n- `logs` to see full logs (typically more detailed than what you see in the console).\n\n- `history` to see recent commands you’ve run.\n\n- `import_item` to add a resource such as a URL or a file to your local workspace.\n\n- `download` downloads a page from a URL, or video/audio media from any of several\n  services like YouTube or Apple Podcasts (using yt-dlp).\n\n- `chat` chat with any configured LLM, and save the chat as a chat document.\n\n- `markdownify` fetches a webpage and converts it to markdown.\n\n- `summarize_as_bullets` summarizes a text document as bulleted items.\n\nIf you use the `kash-media` kit and its dependencies, you get additional actions like:\n\n- `transcribe` transcribes video or audio as text document, using Deepgram.\n\n- `create_pdf` formats Markdown or HTML documents as a PDF.\n\nAll the above commands have help and the ability to see their own source code.\nFor example:\n\n```shell\nmarkdownify --help\nmarkdownify --show_source \n```\n\n## Elements of Kash\n\n### What is Included?\n\nI’ve tried to build independently useful pieces that fit together in a simple way:\n\n- The kash **action framework**:\n\n  - A [**data model**](https://github.com/jlevy/kash/tree/main/kash/model) where\n    documents, resources like URLs, concepts, etc., are saved as files in known formats\n    (Markdown, Markdown+HTML, HTML, YAML resource descriptions, etc.). These and used as\n    `Item`s\n\n  - An **execution model** for `Action`s that take input `Item` inputs and produce\n    outputs, as well as `Parameters` for actions and `Preconditions` that specify what\n    kinds of `Items` the `Action`s operate on (like whether a document is Markdown,\n    HTML, or a transcript with timestamps, and so on), so you and the shell know what\n    actions might apply to any selection\n\n  - A **workspace** which is just a directory of files you are working on, such as a\n    GitHub project or a directory of Markdown files, or anything else, with a `.kash`\n    directory within it to hold cached content and media files, configuration settings\n\n  - A **selection system** in the workspace for maintaining context between commands so\n    you can pass outputs of one action into the inputs of another command (this is a bit\n    like pipes but more flexible for sequences of tasks, possibly with many intermediate\n    inputs and outputs)\n\n  - A simple [**file format for metadata**](https://github.com/jlevy/frontmatter-format)\n    in YAML at the top of text files, so metadata about items can be added to Markdown,\n    HTML, Python, and YAML, as well as detection of file types and conventions for\n    readable filenames based on file type\n\n  - **Dependency tracking** among action operations (sort of like a Makefile) so that\n    Kash can recognize if the output of an action already exists and, if it is\n    cacheable, skip running the action\n\n  - **Python decorators** for functions that let you register and add new commands and\n    actions, which can be packaged into libraries, including libraries with new\n    dependencies\n\n- A **hybrid command-line/natural language/Python shell**, based on\n  [xonsh](https://github.com/xonsh/xonsh)\n\n  - About 100 simple **built-in commands** for listing, showing, and paging through\n    files, etc. (use `commands` for the full list, with docs) plus all usual shell tools\n\n  - Enhanced **tab completion** that includes all actions and commands and parameters,\n    as well as some extras like help summaries populated from\n    [tldr](https://github.com/tldr-pages/tldr)\n\n  - An **LLM-based assistant** that wraps the docs and the kash source code into a tool\n    that assists you in using or extending kash (this part is quite fun!)\n\n- A supporting **library of utilities** to make these work more easily:\n\n  - A library [**chopdiff**](https://github.com/jlevy/chopdiff) to tokenize and parse\n    documents simply into paragraphs, sentences, and words, and do windowed\n    transformations and filtered diffs (such as editing a large document but only\n    inserting section headers or paragraph breaks)\n\n  - A new Markdown auto-formatter, [**flowmark**](https://github.com/jlevy/flowmark), so\n    that text documents (like LLM outputs) are saved in a normalized form that can be\n    diffed consistently\n\n  - A **content and media cache**, which for downloading saving cached versions of video\n    or audio and **audio transcriptions** (using Whisper or Deepgram)\n\n- An optional **enhanced terminal UI** some major enhancements to the terminal\n  experience:\n\n  - Sixel graphics support (see images right in the terminal)\n\n  - A local server for serving information on files as web pages that can be accessed as\n    OSC 8 links\n\n  - Sadly, we may have mind-boggling AI tools, but Terminals are still incredibly\n    archaic and don’t support these features well (more on this below) but I have a new\n    terminal, Kerm, that shows these as tooltips and makes every command clickable\n    (please contact me if you’d like an early developer preview, as I’d love feedback)\n\n## Tools Used by Kash\n\nAll of this is only possible by relying on a wide variety of powerful libraries,\nespecially [xonsh](https://github.com/xonsh/xonsh),\n[Rich](https://github.com/Textualize/rich),\n[LiteLLM](https://github.com/BerriAI/litellm),\n[Pydantic](https://github.com/pydantic/pydantic),\n[Marko](https://github.com/frostming/marko), [yt-dlp](https://github.com/yt-dlp/yt-dlp),\n[Ripgrep](https://github.com/BurntSushi/ripgrep), [Bat](https://github.com/sharkdp/bat),\n[jusText](https://github.com/miso-belica/jusText),\n[WeasyPrint](https://github.com/Kozea/WeasyPrint).\n.\n\n## Tips for Use with Other Tools\n\nWhile not required, these tools can make using kash easier or more fun.\n\n### Choosing a Terminal\n\nYou can use any favorite terminal to run kash.\n\nHowever, you can get a much better terminal experience if you use one with more advanced\nadditional features, such as [OSC 8 link](https://github.com/Alhadis/OSC8-Adoption)\nsupport and [Sixel](https://www.arewesixelyet.com/) graphics.\n\nI tried half a dozen different popular terminals on Mac\n([Terminal](https://support.apple.com/guide/terminal/welcome/mac),\n[Warp](https://www.warp.dev/), [iTerm2](https://iterm2.com/),\n[Kitty](https://sw.kovidgoyal.net/kitty/), [WezTerm](https://wezfurlong.org/wezterm/),\n[Hyper](https://hyper.is/)). Unfortunately, none offer really good support right out of\nthe box, but I encourage you to try\n\n✨**Would you be willing to help test something new?** If you’ve made it this far and are\nstill reading, I have a request.\nSo alongside kash, I’ve begun to build a new terminal app, **Kerm**, that has the\nfeatures we would want in a modern command line, such as clickable links and commands,\ntooltips, and image support.\nKash also takes advantage of this support by embedding OSC 8 links.\nIt is *so* much nicer to use.\nI’d like feedback so please [message me](https://twitter.com/ojoshe) if you’d like to\ntry it out an early dev version!\n\n### Choosing an Editor\n\nMost any editor will work.\nKash respects the `EDITOR` environment variable if you use the `edit` command.\n\n### Using on macOS\n\nKash calls `open` to open some files, so in general, it’s convenient to make sure your\npreferred editor is set up for `.yml` and `.md` files.\n\nFor convenience, a reminder on how to do this:\n\n- In Finder, pick a `.md` or `.yml` file and hit Cmd-I (or right-click and select Get\n  Info).\n\n- Select the editor, such as Cursor or VSCode or Obsidian, and click the “Change All…”\n  button to have it apply to all files with that extension.\n\n- Repeat with each file type.\n\n### Using with Cursor and VSCode\n\n[Cursor](https://www.cursor.com/) and [VSCode](https://code.visualstudio.com/) work fine\nout of the box to edit workspace files in Markdown, HTML, and YAML in kash workspaces.\n\n### Using with Zed\n\n[Zed](https://zed.dev/) is another, newer editor that works great out of the box.\n\n### Using with Obsidian\n\nKash uses Markdown files with YAML frontmatter, which is fully compatible with\n[Obsidian](https://obsidian.md/). Some notes:\n\n- In Obsidian’s preferences, under Editor, turn on “Strict line breaks”.\n\n- This makes the line breaks in kash’s normalized Markdown output work well in Obsidian.\n\n- Some kash files also contain HTML in Markdown.\n  This works fine, but note that only the current line’s HTML is shown in Obsidian.\n\n- Install the [Front Matter Title\n  plugin](https://github.com/snezhig/obsidian-front-matter-title):\n\n  - Go to settings, enable community plugins, search for “Front Matter Title” and\n    install.\n\n  - Under “Installed Plugins,” adjust the settings to enable “Replace shown title in\n    file explorer,” “Replace shown title in graph,” etc.\n\n  - You probably want to keep the “Replace titles in header of leaves” off so you can\n    still see original filenames if needed.\n\n  - Now titles are easy to read for all kash notes.\n\n\u003cbr/\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n⛭\n\n\u003c/div\u003e\n\n* * *\n\n*This project was built from\n[simple-modern-uv](https://github.com/jlevy/simple-modern-uv).*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlevy%2Fkash","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjlevy%2Fkash","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlevy%2Fkash/lists"}