kash-shell 0.3.25__py3-none-any.whl → 0.3.27__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- kash/actions/__init__.py +51 -6
- kash/actions/core/minify_html.py +2 -2
- kash/commands/base/general_commands.py +4 -2
- kash/commands/help/assistant_commands.py +4 -3
- kash/commands/help/welcome.py +1 -1
- kash/config/colors.py +7 -3
- kash/config/logger.py +4 -0
- kash/config/text_styles.py +1 -0
- kash/config/unified_live.py +249 -0
- kash/docs/markdown/assistant_instructions_template.md +3 -3
- kash/docs/markdown/topics/a1_what_is_kash.md +22 -20
- kash/docs/markdown/topics/a2_installation.md +10 -10
- kash/docs/markdown/topics/a3_getting_started.md +8 -8
- kash/docs/markdown/topics/a4_elements.md +3 -3
- kash/docs/markdown/topics/a5_tips_for_use_with_other_tools.md +12 -12
- kash/docs/markdown/topics/b0_philosophy_of_kash.md +17 -17
- kash/docs/markdown/topics/b1_kash_overview.md +7 -7
- kash/docs/markdown/topics/b2_workspace_and_file_formats.md +1 -1
- kash/docs/markdown/topics/b3_modern_shell_tool_recommendations.md +1 -1
- kash/docs/markdown/topics/b4_faq.md +7 -7
- kash/docs/markdown/welcome.md +1 -1
- kash/embeddings/embeddings.py +110 -39
- kash/embeddings/text_similarity.py +2 -2
- kash/exec/shell_callable_action.py +4 -3
- kash/help/help_embeddings.py +5 -2
- kash/mcp/mcp_server_sse.py +0 -5
- kash/model/graph_model.py +2 -0
- kash/model/items_model.py +4 -4
- kash/shell/output/shell_output.py +2 -2
- kash/shell/shell_main.py +64 -6
- kash/shell/version.py +18 -2
- kash/utils/file_utils/csv_utils.py +105 -0
- kash/utils/rich_custom/multitask_status.py +19 -5
- kash/web_gen/templates/base_styles.css.jinja +384 -31
- kash/web_gen/templates/base_webpage.html.jinja +43 -0
- kash/web_gen/templates/components/toc_styles.css.jinja +25 -4
- kash/web_gen/templates/components/tooltip_styles.css.jinja +2 -0
- kash/web_gen/templates/content_styles.css.jinja +23 -9
- kash/web_gen/templates/item_view.html.jinja +12 -4
- kash/web_gen/templates/simple_webpage.html.jinja +2 -2
- kash/xonsh_custom/custom_shell.py +6 -6
- {kash_shell-0.3.25.dist-info → kash_shell-0.3.27.dist-info}/METADATA +59 -56
- {kash_shell-0.3.25.dist-info → kash_shell-0.3.27.dist-info}/RECORD +46 -44
- {kash_shell-0.3.25.dist-info → kash_shell-0.3.27.dist-info}/WHEEL +0 -0
- {kash_shell-0.3.25.dist-info → kash_shell-0.3.27.dist-info}/entry_points.txt +0 -0
- {kash_shell-0.3.25.dist-info → kash_shell-0.3.27.dist-info}/licenses/LICENSE +0 -0
|
@@ -7,6 +7,7 @@
|
|
|
7
7
|
|
|
8
8
|
.citation {
|
|
9
9
|
font-family: var(--font-sans);
|
|
10
|
+
font-feature-settings: var(--font-features-sans);
|
|
10
11
|
color: var(--color-secondary);
|
|
11
12
|
display: inline-block;
|
|
12
13
|
height: 1.3rem;
|
|
@@ -37,6 +38,7 @@
|
|
|
37
38
|
|
|
38
39
|
.description {
|
|
39
40
|
font-family: var(--font-sans);
|
|
41
|
+
font-feature-settings: var(--font-features-sans);
|
|
40
42
|
font-size: var(--font-size-small);
|
|
41
43
|
color: var(--color-secondary);
|
|
42
44
|
margin: 2rem 0;
|
|
@@ -44,6 +46,7 @@
|
|
|
44
46
|
|
|
45
47
|
.summary {
|
|
46
48
|
font-family: var(--font-sans);
|
|
49
|
+
font-feature-settings: var(--font-features-sans);
|
|
47
50
|
font-size: var(--font-size-small);
|
|
48
51
|
margin: 1rem 0;
|
|
49
52
|
padding: 1rem;
|
|
@@ -54,15 +57,19 @@
|
|
|
54
57
|
display: block;
|
|
55
58
|
text-align: center;
|
|
56
59
|
font-family: var(--font-sans);
|
|
60
|
+
font-feature-settings: var(--font-features-sans);
|
|
57
61
|
font-weight: 500;
|
|
58
|
-
font-size: 1.2rem;
|
|
59
|
-
|
|
60
|
-
|
|
62
|
+
font-size: calc(1.2rem * var(--caps-heading-size-multiplier));
|
|
63
|
+
line-height: var(--caps-heading-line-height);
|
|
64
|
+
text-transform: var(--caps-transform);
|
|
65
|
+
font-variant-caps: var(--caps-caps-variant);
|
|
66
|
+
letter-spacing: var(--caps-spacing);
|
|
61
67
|
margin-bottom: 0.5rem;
|
|
62
68
|
}
|
|
63
69
|
|
|
64
70
|
.concepts {
|
|
65
71
|
font-family: var(--font-sans);
|
|
72
|
+
font-feature-settings: var(--font-features-sans);
|
|
66
73
|
font-size: var(--font-size-small);
|
|
67
74
|
font-weight: bold;
|
|
68
75
|
margin: 2rem 0;
|
|
@@ -79,10 +86,13 @@
|
|
|
79
86
|
display: block;
|
|
80
87
|
text-align: center;
|
|
81
88
|
font-family: var(--font-sans);
|
|
89
|
+
font-feature-settings: var(--font-features-sans);
|
|
82
90
|
font-weight: 500;
|
|
83
|
-
font-size: 1.2rem;
|
|
84
|
-
|
|
85
|
-
|
|
91
|
+
font-size: calc(1.2rem * var(--caps-heading-size-multiplier));
|
|
92
|
+
line-height: var(--caps-heading-line-height);
|
|
93
|
+
text-transform: var(--caps-transform);
|
|
94
|
+
font-variant-caps: var(--caps-caps-variant);
|
|
95
|
+
letter-spacing: var(--caps-spacing);
|
|
86
96
|
margin-bottom: 0.5rem;
|
|
87
97
|
|
|
88
98
|
/* Hack to center the header above the columns */
|
|
@@ -106,10 +116,13 @@
|
|
|
106
116
|
max-width: 10rem;
|
|
107
117
|
text-align: center;
|
|
108
118
|
font-family: var(--font-sans);
|
|
109
|
-
font-
|
|
119
|
+
font-feature-settings: var(--font-features-sans);
|
|
110
120
|
font-weight: 600;
|
|
111
|
-
|
|
112
|
-
|
|
121
|
+
font-size: calc(var(--font-size-small) * var(--caps-heading-size-multiplier));
|
|
122
|
+
line-height: var(--caps-heading-line-height);
|
|
123
|
+
text-transform: var(--caps-transform);
|
|
124
|
+
font-variant-caps: var(--caps-caps-variant);
|
|
125
|
+
letter-spacing: var(--caps-spacing);
|
|
113
126
|
line-height: 1.2;
|
|
114
127
|
padding: 0 0.5rem;
|
|
115
128
|
border-bottom-width: 2px;
|
|
@@ -171,6 +184,7 @@
|
|
|
171
184
|
order: 0;
|
|
172
185
|
margin: 0.5rem 1rem 0.5rem 0;
|
|
173
186
|
font-family: var(--font-sans);
|
|
187
|
+
font-feature-settings: var(--font-features-sans);
|
|
174
188
|
color: var(--color-secondary);
|
|
175
189
|
border-right: 2px solid var(--color-hint);
|
|
176
190
|
padding-right: 0.5rem;
|
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
<style>
|
|
3
3
|
.item-view {
|
|
4
4
|
font-family: var(--font-sans);
|
|
5
|
+
font-feature-settings: var(--font-features-sans);
|
|
5
6
|
{# TODO: Consider putting a border to indicate type of info. But have to
|
|
6
7
|
make sure it does not grow the tooltip inadverently. #}
|
|
7
8
|
{# border-left: 3px solid var(--color-border-accent);
|
|
@@ -19,9 +20,12 @@
|
|
|
19
20
|
|
|
20
21
|
.item-type {
|
|
21
22
|
font-family: var(--font-sans);
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
23
|
+
font-feature-settings: var(--font-features-sans);
|
|
24
|
+
font-size: calc(var(--font-size-smaller) * var(--caps-heading-size-multiplier));
|
|
25
|
+
line-height: var(--caps-heading-line-height);
|
|
26
|
+
text-transform: var(--caps-transform);
|
|
27
|
+
font-variant-caps: var(--caps-caps-variant);
|
|
28
|
+
letter-spacing: var(--caps-spacing);
|
|
25
29
|
font-weight: var(--font-weight-sans-bold);
|
|
26
30
|
padding-right: 1rem;
|
|
27
31
|
}
|
|
@@ -108,7 +112,8 @@ h1.item-title {
|
|
|
108
112
|
}
|
|
109
113
|
|
|
110
114
|
.item-file-info {
|
|
111
|
-
{# font-family: var(--font-sans);
|
|
115
|
+
{# font-family: var(--font-sans);
|
|
116
|
+
font-feature-settings: var(--font-features-sans); #}
|
|
112
117
|
padding: 0;
|
|
113
118
|
{# font-size: var(--font-size-mono-small); #}
|
|
114
119
|
word-break: break-word;
|
|
@@ -116,6 +121,7 @@ h1.item-title {
|
|
|
116
121
|
|
|
117
122
|
.item-file-info pre {
|
|
118
123
|
font-family: var(--font-sans);
|
|
124
|
+
font-feature-settings: var(--font-features-sans);
|
|
119
125
|
font-size: var(--font-size-small);
|
|
120
126
|
letter-spacing: 0;
|
|
121
127
|
border: none;
|
|
@@ -137,6 +143,7 @@ h1.item-title {
|
|
|
137
143
|
|
|
138
144
|
.item-description {
|
|
139
145
|
font-family: var(--font-sans);
|
|
146
|
+
font-feature-settings: var(--font-features-sans);
|
|
140
147
|
font-size: var(--font-size-small);
|
|
141
148
|
padding: 0.5rem 0;
|
|
142
149
|
}
|
|
@@ -153,6 +160,7 @@ h1.item-title {
|
|
|
153
160
|
.item-footer {
|
|
154
161
|
padding: 0.5rem 1rem;
|
|
155
162
|
font-family: var(--font-sans);
|
|
163
|
+
font-feature-settings: var(--font-features-sans);
|
|
156
164
|
font-size: var(--font-size-smaller);
|
|
157
165
|
color: var(--color-secondary);
|
|
158
166
|
}
|
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
<style>
|
|
6
6
|
/* Override Tailwind's bg-white in dark mode */
|
|
7
7
|
[data-theme="dark"] .bg-white {
|
|
8
|
-
background-color: var(--color-bg
|
|
8
|
+
background-color: var(--color-bg);
|
|
9
9
|
}
|
|
10
10
|
|
|
11
11
|
/* Fallback responsive padding for compatibility */
|
|
@@ -21,7 +21,7 @@
|
|
|
21
21
|
|
|
22
22
|
/* Ensure long-text containers respect theme */
|
|
23
23
|
[data-theme="dark"] .long-text {
|
|
24
|
-
background-color: var(--color-bg
|
|
24
|
+
background-color: var(--color-bg);
|
|
25
25
|
color: var(--color-text);
|
|
26
26
|
box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.3), 0 -2px 6px -1px rgba(0, 0, 0, 0.2);
|
|
27
27
|
}
|
|
@@ -23,13 +23,12 @@ from xonsh.shells.ptk_shell.formatter import PTKPromptFormatter
|
|
|
23
23
|
from xonsh.xontribs import xontribs_load
|
|
24
24
|
|
|
25
25
|
import kash.config.suppress_warnings # noqa: F401 # usort:skip
|
|
26
|
-
|
|
27
|
-
# Keeping initial imports/deps minimal.
|
|
28
26
|
from kash.config import colors
|
|
29
27
|
from kash.config.lazy_imports import import_start_time # usort:skip
|
|
30
|
-
from kash.config.logger import
|
|
28
|
+
from kash.config.logger import get_log_settings, get_logger
|
|
31
29
|
from kash.config.settings import APP_NAME, find_rcfiles
|
|
32
|
-
from kash.config.text_styles import
|
|
30
|
+
from kash.config.text_styles import STYLE_ASSISTANCE, STYLE_HINT
|
|
31
|
+
from kash.config.unified_live import get_unified_live
|
|
33
32
|
from kash.help.assistant import AssistanceType
|
|
34
33
|
from kash.shell.output.shell_output import cprint
|
|
35
34
|
from kash.shell.ui.shell_syntax import is_assist_request_str
|
|
@@ -175,7 +174,7 @@ class CustomAssistantShell(PromptToolkitShell):
|
|
|
175
174
|
assist_query = is_assist_request_str(line)
|
|
176
175
|
if assist_query:
|
|
177
176
|
try:
|
|
178
|
-
with
|
|
177
|
+
with get_unified_live().status("Thinking…"):
|
|
179
178
|
shell_context_assistance(assist_query, assistance_type=AssistanceType.fast)
|
|
180
179
|
except Exception as e:
|
|
181
180
|
log.error(f"Sorry, could not get assistance: {abbrev_str(str(e), max_len=1000)}")
|
|
@@ -310,7 +309,8 @@ def assistance_on_not_found(cmd: list[str]):
|
|
|
310
309
|
from kash.help.assistant import shell_context_assistance
|
|
311
310
|
|
|
312
311
|
cprint("Command was not recognized.", style=STYLE_ASSISTANCE)
|
|
313
|
-
|
|
312
|
+
|
|
313
|
+
with get_unified_live().status("Thinking…"):
|
|
314
314
|
shell_context_assistance(
|
|
315
315
|
f"""
|
|
316
316
|
The user just typed the following command, but it was not found:
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: kash-shell
|
|
3
|
-
Version: 0.3.
|
|
3
|
+
Version: 0.3.27
|
|
4
4
|
Summary: The knowledge agent shell (core)
|
|
5
5
|
Project-URL: Repository, https://github.com/jlevy/kash-shell
|
|
6
6
|
Author-email: Joshua Levy <joshua@cal.berkeley.edu>
|
|
@@ -28,7 +28,7 @@ Requires-Dist: curl-cffi>=0.11.4
|
|
|
28
28
|
Requires-Dist: deepgram-sdk>=3.10.1
|
|
29
29
|
Requires-Dist: dunamai>=1.23.0
|
|
30
30
|
Requires-Dist: fastapi>=0.115.11
|
|
31
|
-
Requires-Dist: flowmark>=0.
|
|
31
|
+
Requires-Dist: flowmark>=0.5.2
|
|
32
32
|
Requires-Dist: frontmatter-format>=0.2.1
|
|
33
33
|
Requires-Dist: funlog>=0.2.0
|
|
34
34
|
Requires-Dist: httpx[brotli]>=0.28.1
|
|
@@ -41,7 +41,6 @@ Requires-Dist: litellm>=1.63.11
|
|
|
41
41
|
Requires-Dist: markdownify>=0.13.1
|
|
42
42
|
Requires-Dist: mcp-proxy>=0.5.0
|
|
43
43
|
Requires-Dist: mcp>=1.6.0
|
|
44
|
-
Requires-Dist: minify-tw-html>=0.1.3
|
|
45
44
|
Requires-Dist: openai>=1.66.3
|
|
46
45
|
Requires-Dist: pandas>=2.2.3
|
|
47
46
|
Requires-Dist: patch-ng>=1.18.1
|
|
@@ -57,6 +56,7 @@ Requires-Dist: pyrate-limiter>=3.7.0
|
|
|
57
56
|
Requires-Dist: python-dotenv>=1.0.1
|
|
58
57
|
Requires-Dist: python-magic-bin>=0.4.14; platform_system == 'Windows'
|
|
59
58
|
Requires-Dist: python-magic>=0.4.27; platform_system == 'Linux' or platform_system == 'Darwin'
|
|
59
|
+
Requires-Dist: questionary>=2.0.0
|
|
60
60
|
Requires-Dist: readabilipy>=0.3.0
|
|
61
61
|
Requires-Dist: regex>=2024.11.6
|
|
62
62
|
Requires-Dist: rich-argparse>=1.7.0
|
|
@@ -69,6 +69,7 @@ Requires-Dist: tenacity>=9.0.0
|
|
|
69
69
|
Requires-Dist: thefuzz>=0.22.1
|
|
70
70
|
Requires-Dist: tiktoken>=0.9.0
|
|
71
71
|
Requires-Dist: tldr>=3.3.0
|
|
72
|
+
Requires-Dist: tminify>=0.1.6
|
|
72
73
|
Requires-Dist: typing-extensions>=4.12.2
|
|
73
74
|
Requires-Dist: uvicorn>=0.34.0
|
|
74
75
|
Requires-Dist: xonsh>=0.19.3
|
|
@@ -93,15 +94,15 @@ exploratory, and flexible using Python and current AI tools.
|
|
|
93
94
|
|
|
94
95
|
The philosophy behind kash is similar to Unix shell tools: simple commands that can be
|
|
95
96
|
combined in flexible and powerful ways.
|
|
96
|
-
It operates on
|
|
97
|
+
It operates on “items” such as URLs, files, or Markdown notes within a workspace
|
|
97
98
|
directory.
|
|
98
99
|
|
|
99
100
|
You can use Kash as an **interactive, AI-native command-line** shell for practical
|
|
100
|
-
knowledge tasks. It
|
|
101
|
+
knowledge tasks. It’s also **a Python library** that lets you convert a simple Python
|
|
101
102
|
function into a command and an MCP tool, so it integrates with other tools like
|
|
102
103
|
Anthropic Desktop or Cursor.
|
|
103
104
|
|
|
104
|
-
It
|
|
105
|
+
It’s new and still has some rough edges, but it’s now working well enough it is feeling
|
|
105
106
|
quite powerful. It now serves as a replacement for my usual shell (previously bash or
|
|
106
107
|
zsh). I use it routinely to remix, combine, and interactively explore and then gradually
|
|
107
108
|
automate complex tasks by composing AI tools, APIs, and libraries.
|
|
@@ -133,19 +134,20 @@ quick to install via uv.
|
|
|
133
134
|
context of a **workspace**. A workspace is just a directory of files that have a few
|
|
134
135
|
conventions to make it easier to maintain context and perform actions.
|
|
135
136
|
A bit like how Git repos work, it has a `.kash/` directory that holds metadata and
|
|
136
|
-
cached content. The rest can be anything, but is typically directories of
|
|
137
|
-
(
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
137
|
+
cached content. The rest can be anything, but is typically directories of content and
|
|
138
|
+
resources (often Markdown or HTML but also .docx or .pdf or links to web pages).
|
|
139
|
+
All text files use [frontmatter-format](https://github.com/jlevy/frontmatter-format)
|
|
140
|
+
so have YAML metadata that includes not just title or description, but also how it was
|
|
141
|
+
created. All Markdown files are auto-formatted with
|
|
142
|
+
[flowmark](https://github.com/jlevy/flowmark), which makes documents much easier to
|
|
143
|
+
diff and version control (and prettier to read and edit).
|
|
142
144
|
|
|
143
145
|
- **Compositionality:** An action is composable with other actions simply as a Python
|
|
144
146
|
function, so complex operations (for example, transcribing and annotating a video and
|
|
145
147
|
publishing it on a website) actions can be built from simpler actions (say downloading
|
|
146
148
|
and caching a YouTube video, identifying the speakers in a transcript, formatting it
|
|
147
|
-
as pretty HTML, etc.). The goal is to reduce the
|
|
148
|
-
combining tools, so it
|
|
149
|
+
as pretty HTML, etc.). The goal is to reduce the “interstitial complexity” of
|
|
150
|
+
combining tools, so it’s easy for you (or an LLM!) to combine tools in flexible and
|
|
149
151
|
powerful ways.
|
|
150
152
|
|
|
151
153
|
- **Command-line usage:** In addition to using the function in other libraries and
|
|
@@ -172,16 +174,16 @@ transcripts and notes, write blog posts, extract or visualize concepts, check ci
|
|
|
172
174
|
convert notes to PDFs or beautifully formatted HTML, or perform numerous other
|
|
173
175
|
content-related tasks possible by orchestrating AI tools in the right ways.
|
|
174
176
|
|
|
175
|
-
As I
|
|
177
|
+
As I’ve been building kash over the past couple months, I found I’ve found it’s not only
|
|
176
178
|
faster to do complex things, but that it has also become replacement for my usual shell.
|
|
177
|
-
It
|
|
179
|
+
It’s the power-tool I want to use alongside Cursor and ChatGPT/Claude.
|
|
178
180
|
We all know and trust shells like bash, zsh, and fish, but now I find this is much more
|
|
179
181
|
powerful for everyday usage.
|
|
180
182
|
It has little niceties, like you can just type `files` for a better listing of files or
|
|
181
183
|
`show` and it will show you a file the right way, no matter what kind of file it is.
|
|
182
|
-
You can also type something like
|
|
184
|
+
You can also type something like “? find md files” and press tab and it will list you I
|
|
183
185
|
find it is much more powerful for local usage than than bash/zsh/fish.
|
|
184
|
-
If you
|
|
186
|
+
If you’re a command-line nerd, you might like it a lot.
|
|
185
187
|
|
|
186
188
|
But my hope is that with these enhancements, the shell is also far more friendly and
|
|
187
189
|
usable by anyone reasonably technical, and does not feel so esoteric as a typical Unix
|
|
@@ -190,16 +192,17 @@ shell.
|
|
|
190
192
|
Finally, one more thing: Kash is also my way of experimenting with something else new: a
|
|
191
193
|
**terminal GUI support** that adds GUI features terminal like clickable text, buttons,
|
|
192
194
|
tooltips, and popovers in the terminal.
|
|
193
|
-
I
|
|
194
|
-
|
|
195
|
+
I’ve separately built a new desktop terminal app, Kerm, which adds support for a simple
|
|
196
|
+
“Kerm codes” protocol for such visual components, encoded as OSC codes then rendered in
|
|
195
197
|
the terminal. Because Kash supports these codes, as this develops you will get the
|
|
196
198
|
visuals of a web app layered on the flexibility of a text-based terminal.
|
|
197
199
|
|
|
198
200
|
### Is Kash Mature?
|
|
199
201
|
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
202
|
+
It’s the result of a couple months of coding and experimentation, and it’s still in
|
|
203
|
+
progress and has rough edges.
|
|
204
|
+
Please help me make it better by sharing your ideas and feedback!
|
|
205
|
+
It’s easiest to DM me at [twitter.com/ojoshe](https://x.com/ojoshe).
|
|
203
206
|
My contact info is at [github.com/jlevy](https://github.com/jlevy).
|
|
204
207
|
|
|
205
208
|
[**Please follow or DM me**](https://x.com/ojoshe) for future updates or if you have
|
|
@@ -211,7 +214,7 @@ ideas, feedback, or use cases for Kash!
|
|
|
211
214
|
|
|
212
215
|
Kash offers a shell environment based on [xonsh](https://xon.sh/) augmented with a bunch
|
|
213
216
|
of enhanced commands and customizations.
|
|
214
|
-
If you
|
|
217
|
+
If you’ve used a bash or Python shell before, it should be very intuitive.
|
|
215
218
|
|
|
216
219
|
Within the kash shell, you get a full environment with all actions and commands.
|
|
217
220
|
You also get intelligent auto-complete, a built-in assistant to help you perform tasks,
|
|
@@ -220,7 +223,7 @@ and enhanced tab completion.
|
|
|
220
223
|
The shell is an easy way to use Kash actions, simply calling them like other shell
|
|
221
224
|
commands from the command line.
|
|
222
225
|
|
|
223
|
-
But remember that
|
|
226
|
+
But remember that’s just one way to use actions; you can also use them directly in
|
|
224
227
|
Python or from an MCP client.
|
|
225
228
|
|
|
226
229
|
### Current Kash Packages
|
|
@@ -230,7 +233,7 @@ However, some use cases require additional libraries, like video downloading too
|
|
|
230
233
|
handling, etc.
|
|
231
234
|
|
|
232
235
|
To keep kash dependencies more manageable, these additional utilities and actions are
|
|
233
|
-
packaged additional
|
|
236
|
+
packaged additional “kits”.
|
|
234
237
|
|
|
235
238
|
The examples below use video transcription from YouTube as an example.
|
|
236
239
|
To start with more full examples, I suggest starting with the `kash-media` kit.
|
|
@@ -245,7 +248,7 @@ These are for `kash-media` but you can use a `kash-shell` for a more basic setup
|
|
|
245
248
|
Kash is easiest to use via [**uv**](https://docs.astral.sh/uv/), the new package
|
|
246
249
|
manager for Python. `uv` replaces traditional use of `pyenv`, `pipx`, `poetry`, `pip`,
|
|
247
250
|
etc. Installing `uv` also ensures you get a compatible version of Python.
|
|
248
|
-
See [uv
|
|
251
|
+
See [uv’s docs](https://docs.astral.sh/uv/getting-started/installation/) for other
|
|
249
252
|
installation methods and platforms.
|
|
250
253
|
Usually you just want to run:
|
|
251
254
|
```shell
|
|
@@ -254,7 +257,7 @@ These are for `kash-media` but you can use a `kash-shell` for a more basic setup
|
|
|
254
257
|
|
|
255
258
|
2. **Install additional command-line tools:**
|
|
256
259
|
|
|
257
|
-
In addition to Python, it
|
|
260
|
+
In addition to Python, it’s highly recommended to install a few other dependencies to
|
|
258
261
|
make more tools and commands work.
|
|
259
262
|
For macOS, you can again use brew:
|
|
260
263
|
|
|
@@ -311,7 +314,7 @@ These are for `kash-media` but you can use a `kash-shell` for a more basic setup
|
|
|
311
314
|
```
|
|
312
315
|
|
|
313
316
|
These keys should go in the `.env` file in your current work directory or a parent or
|
|
314
|
-
your home directory (recommended if you
|
|
317
|
+
your home directory (recommended if you’ll be working in several directories, as with
|
|
315
318
|
a typical shell).
|
|
316
319
|
|
|
317
320
|
5. **Run kash:**
|
|
@@ -351,14 +354,14 @@ If you add the `--proxy` arg, it will run an MCP stdio server but connect to the
|
|
|
351
354
|
server you are running in the kash shell, by default at `localhost:4440`.
|
|
352
355
|
|
|
353
356
|
Then if you run `start_mcp_server` from the shell, your client will connect to your
|
|
354
|
-
shell, and you can actually use any
|
|
357
|
+
shell, and you can actually use any “published” kash action as an MCP tool.
|
|
355
358
|
|
|
356
|
-
Then you can for example ask your MCP client
|
|
359
|
+
Then you can for example ask your MCP client “can you transcribe this video?”
|
|
357
360
|
and give it a URL, and it will be able to call the `transcribe` action as a tool.
|
|
358
361
|
|
|
359
362
|
What is even better is that all the inputs and outputs are saved in the current kash
|
|
360
|
-
workspace, just as if you
|
|
361
|
-
This way, you don
|
|
363
|
+
workspace, just as if you’d been running these commands yourself in the shell.
|
|
364
|
+
This way, you don’t lose context or any work, and can seamlessly switch between an MCP
|
|
362
365
|
client like Cursor, the shell, and any other tools to edit the inputs or outputs of
|
|
363
366
|
actions in your workspace directory.
|
|
364
367
|
|
|
@@ -383,11 +386,11 @@ Type `help` for the full documentation.
|
|
|
383
386
|
The simplest way to illustrate how to use kash is by example.
|
|
384
387
|
You can go through the commands below a few at a time, trying each one.
|
|
385
388
|
|
|
386
|
-
This is a
|
|
387
|
-
So to get it to work you must install not just the main shell but the kash
|
|
389
|
+
This is a “real” example that uses ffmpeg and a few other libraries.
|
|
390
|
+
So to get it to work you must install not just the main shell but the kash “media kit”
|
|
388
391
|
with extra dependencies.
|
|
389
392
|
This is discussed in [the installation instructions](#installation-steps).
|
|
390
|
-
If you don
|
|
393
|
+
If you don’t have these already installed, you can add these tools:
|
|
391
394
|
|
|
392
395
|
Then run `kash` to start.
|
|
393
396
|
|
|
@@ -538,8 +541,8 @@ All of these steps are just actions.
|
|
|
538
541
|
|
|
539
542
|
### Creating a New Workspace
|
|
540
543
|
|
|
541
|
-
Although you don
|
|
542
|
-
kash. It
|
|
544
|
+
Although you don’t always need one, a *workspace* is very helpful for any real work in
|
|
545
|
+
kash. It’s just a directory of files, plus a `.kash/` directory with various logs and
|
|
543
546
|
metadata.
|
|
544
547
|
|
|
545
548
|
Note the `.kash/cache` directory contains all the downloaded videos and media you
|
|
@@ -560,7 +563,7 @@ By default, when you are not using the shell inside a workspace directory, or wh
|
|
|
560
563
|
run kash the first time, it uses the default *global workspace*.
|
|
561
564
|
|
|
562
565
|
Once you create a workspace, you can `cd` into that workspace and that will become the
|
|
563
|
-
current workspace. (If you
|
|
566
|
+
current workspace. (If you’re familiar with how the `git` command-line works in
|
|
564
567
|
conjunction with the `.git/` directory, this behavior is very similar.)
|
|
565
568
|
|
|
566
569
|
To start a new workspace, run a command like
|
|
@@ -598,7 +601,7 @@ A few of the most important commands for managing files and work are these:
|
|
|
598
601
|
|
|
599
602
|
- `workspace` shows or selects or creates a new workspace.
|
|
600
603
|
Initially you work in the default global workspace (typically at `~/Kash/workspace`)
|
|
601
|
-
but for more real work you
|
|
604
|
+
but for more real work you’ll want to create a workspace, which is a directory to hold
|
|
602
605
|
the files you are working with.
|
|
603
606
|
|
|
604
607
|
- `select` shows or sets selections, which are the set of files the next command will
|
|
@@ -612,7 +615,7 @@ A few of the most important commands for managing files and work are these:
|
|
|
612
615
|
|
|
613
616
|
- `logs` to see full logs (typically more detailed than what you see in the console).
|
|
614
617
|
|
|
615
|
-
- `history` to see recent commands you
|
|
618
|
+
- `history` to see recent commands you’ve run.
|
|
616
619
|
|
|
617
620
|
- `import_item` to add a resource such as a URL or a file to your local workspace.
|
|
618
621
|
|
|
@@ -643,7 +646,7 @@ markdownify --show_source
|
|
|
643
646
|
|
|
644
647
|
### What is Included?
|
|
645
648
|
|
|
646
|
-
I
|
|
649
|
+
I’ve tried to build independently useful pieces that fit together in a simple way:
|
|
647
650
|
|
|
648
651
|
- The kash **action framework**:
|
|
649
652
|
|
|
@@ -716,9 +719,9 @@ I've tried to build independently useful pieces that fit together in a simple wa
|
|
|
716
719
|
OSC 8 links
|
|
717
720
|
|
|
718
721
|
- Sadly, we may have mind-boggling AI tools, but Terminals are still incredibly
|
|
719
|
-
archaic and don
|
|
722
|
+
archaic and don’t support these features well (more on this below) but I have a new
|
|
720
723
|
terminal, Kerm, that shows these as tooltips and makes every command clickable
|
|
721
|
-
(please contact me if you
|
|
724
|
+
(please contact me if you’d like an early developer preview, as I’d love feedback)
|
|
722
725
|
|
|
723
726
|
## Tools Used by Kash
|
|
724
727
|
|
|
@@ -752,14 +755,14 @@ I tried half a dozen different popular terminals on Mac
|
|
|
752
755
|
[Hyper](https://hyper.is/)). Unfortunately, none offer really good support right out of
|
|
753
756
|
the box, but I encourage you to try
|
|
754
757
|
|
|
755
|
-
✨**Would you be willing to help test something new?** If you
|
|
758
|
+
✨**Would you be willing to help test something new?** If you’ve made it this far and are
|
|
756
759
|
still reading, I have a request.
|
|
757
|
-
So alongside kash, I
|
|
760
|
+
So alongside kash, I’ve begun to build a new terminal app, **Kerm**, that has the
|
|
758
761
|
features we would want in a modern command line, such as clickable links and commands,
|
|
759
762
|
tooltips, and image support.
|
|
760
763
|
Kash also takes advantage of this support by embedding OSC 8 links.
|
|
761
764
|
It is *so* much nicer to use.
|
|
762
|
-
I
|
|
765
|
+
I’d like feedback so please [message me](https://twitter.com/ojoshe) if you’d like to
|
|
763
766
|
try it out an early dev version!
|
|
764
767
|
|
|
765
768
|
### Choosing an Editor
|
|
@@ -769,7 +772,7 @@ Kash respects the `EDITOR` environment variable if you use the `edit` command.
|
|
|
769
772
|
|
|
770
773
|
### Using on macOS
|
|
771
774
|
|
|
772
|
-
Kash calls `open` to open some files, so in general, it
|
|
775
|
+
Kash calls `open` to open some files, so in general, it’s convenient to make sure your
|
|
773
776
|
preferred editor is set up for `.yml` and `.md` files.
|
|
774
777
|
|
|
775
778
|
For convenience, a reminder on how to do this:
|
|
@@ -777,7 +780,7 @@ For convenience, a reminder on how to do this:
|
|
|
777
780
|
- In Finder, pick a `.md` or `.yml` file and hit Cmd-I (or right-click and select Get
|
|
778
781
|
Info).
|
|
779
782
|
|
|
780
|
-
- Select the editor, such as Cursor or VSCode or Obsidian, and click the
|
|
783
|
+
- Select the editor, such as Cursor or VSCode or Obsidian, and click the “Change All…”
|
|
781
784
|
button to have it apply to all files with that extension.
|
|
782
785
|
|
|
783
786
|
- Repeat with each file type.
|
|
@@ -796,23 +799,23 @@ out of the box to edit workspace files in Markdown, HTML, and YAML in kash works
|
|
|
796
799
|
Kash uses Markdown files with YAML frontmatter, which is fully compatible with
|
|
797
800
|
[Obsidian](https://obsidian.md/). Some notes:
|
|
798
801
|
|
|
799
|
-
- In Obsidian
|
|
802
|
+
- In Obsidian’s preferences, under Editor, turn on “Strict line breaks”.
|
|
800
803
|
|
|
801
|
-
- This makes the line breaks in kash
|
|
804
|
+
- This makes the line breaks in kash’s normalized Markdown output work well in Obsidian.
|
|
802
805
|
|
|
803
806
|
- Some kash files also contain HTML in Markdown.
|
|
804
|
-
This works fine, but note that only the current line
|
|
807
|
+
This works fine, but note that only the current line’s HTML is shown in Obsidian.
|
|
805
808
|
|
|
806
809
|
- Install the [Front Matter Title
|
|
807
810
|
plugin](https://github.com/snezhig/obsidian-front-matter-title):
|
|
808
811
|
|
|
809
|
-
- Go to settings, enable community plugins, search for
|
|
812
|
+
- Go to settings, enable community plugins, search for “Front Matter Title” and
|
|
810
813
|
install.
|
|
811
814
|
|
|
812
|
-
- Under
|
|
813
|
-
file explorer
|
|
815
|
+
- Under “Installed Plugins,” adjust the settings to enable “Replace shown title in
|
|
816
|
+
file explorer,” “Replace shown title in graph,” etc.
|
|
814
817
|
|
|
815
|
-
- You probably want to keep the
|
|
818
|
+
- You probably want to keep the “Replace titles in header of leaves” off so you can
|
|
816
819
|
still see original filenames if needed.
|
|
817
820
|
|
|
818
821
|
- Now titles are easy to read for all kash notes.
|