feat: add RTK guidance and shell rewrites

Author: LK4D4

README.md

@@ -27,5 +27,7 @@ Agent-facing install steps live in [`CODEX_INSTALL.md`](CODEX_INSTALL.md).
 it can suggest a safer RTK-shaped command. Ambiguous, unsupported, malformed, or
 mutating commands fail open with no output.
 
+Repo-tested Codex usage guidance lives in [`RTK.md`](RTK.md).
+
 Developer docs, release steps, debugging, and full rewrite details live in
 [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md).

RTK.md

@@ -0,0 +1,121 @@
+# RTK Guidance For Codex
+
+RTK saves context by filtering noisy command output before it reaches Codex.
+Use it deliberately for commands that usually produce many tokens.
+
+## Default
+
+Prefer `rtk` for supported noisy commands:
+
+```bash
+rtk git status --short
+rtk git diff -- src tests
+rtk cargo test
+rtk cargo clippy --all-targets --all-features -- -D warnings
+rtk npm run build
+rtk pytest -q
+rtk gh run view <id>
+```
+
+Do not blindly prefix every shell command. Keep shell/control/device tools raw
+when RTK does not support them, or use `rtk proxy <cmd>` as an escape hatch.
+Common raw tools: `pwsh`, `powershell`, `bash`, `sh`, `adb`, `sqlite3`, `jq`,
+`node`, `where.exe`, `which`, direct scripts, and direct local binaries.
+
+## Read Files
+
+Use `rtk read` instead of `cat`, `Get-Content`, `sed -n`, `head`, `tail`, or
+`nl -ba` when inspecting known files:
+
+```bash
+rtk read src/main.rs
+rtk read -n src/main.rs
+rtk read src/main.rs --max-lines 120
+rtk read app.log --tail-lines 80
+```
+
+Real flags: `--line-numbers`/`-n`, `--max-lines`, `--tail-lines`, and
+`--level none|minimal|aggressive`. Do not invent `--range`, `--line`, or
+`--lines`.
+
+## Filter Levels And Smart Reads
+
+Use read levels intentionally. The flag is `--level <level>` or `-l <level>`;
+do not use standalone `--minimal` or `--aggressive` unless RTK adds those flags.
+
+```bash
+rtk read src/main.rs --level none
+rtk read src/main.rs --level minimal
+rtk read -n src/main.rs --level aggressive
+rtk smart src/main.rs
+```
+
+Use `none` or omit `--level` when exact text matters, especially short files,
+line-sensitive code, configs, or useful file headers/comments. Add
+`--max-lines` or `--tail-lines` to keep exact top/tail windows small.
+
+Use `minimal` for compact first reads of medium or large files when comments and
+blank lines are less important than code shape.
+
+Use `aggressive` for structure scans of large unfamiliar files, then follow with
+targeted `rtk grep` or exact `rtk read` windows.
+
+Use `rtk smart <file>` for a quick heuristic summary of an unfamiliar source
+file before deciding what to read next. Do not use it as a substitute for exact
+code when editing or reviewing line-level behavior.
+
+## Search And Discovery
+
+Use `rtk grep` for content search and `rtk find` for file discovery:
+
+```bash
+rtk grep -n "pattern" src tests
+rtk grep -n "pattern|other" .
+rtk find .
+rtk find src -name "*.rs"
+```
+
+Use `rtk find`, not `rtk rg --files` or `rtk grep --files`. If raw `rg` is
+needed for a complex mode, keep it raw or use `rtk proxy rg ...`.
+
+## Shell Wrappers
+
+Avoid shell wrappers for simple commands:
+
+```bash
+rtk git status
+rtk cargo test
+```
+
+Use a wrapper only when shell features are needed, such as environment setup,
+compound commands, redirects, or here-docs. Keep the wrapper raw and put `rtk`
+on the noisy inner command when safe:
+
+```bash
+pwsh -NoProfile -Command '$env:PATH="$env:APPDATA\luarocks\bin;$env:PATH"; rtk busted spec'
+bash -lc 'PATH="$HOME/.luarocks/bin:$PATH" rtk busted spec'
+env PATH="$HOME/.luarocks/bin:$PATH" rtk luacheck --codes spec
+```
+
+For structured or already-bounded output, raw may be better than RTK:
+
+```bash
+jq . file.json
+where.exe rtk
+which rtk
+adb devices
+```
+
+## Check Savings
+
+```bash
+rtk gain
+rtk gain --history
+rtk gain --failures
+rtk --help
+rtk proxy <cmd>
+```
+
+High-value habits from observed runs: use `rtk grep` for broad recursive
+searches, `rtk read` for memory/session/source files, `rtk find` for recursive
+file lists, and `rtk cargo test`/test wrappers for noisy test output.

docs/DEVELOPMENT.md

@@ -120,6 +120,10 @@ Rewrite order:
 - PowerShell wrappers around `busted` and `luacheck` keep the `pwsh` wrapper
   for environment setup while applying `rtk` to the noisy inner tool. Existing
   unsupported `rtk pwsh ...` commands are rewritten back to `pwsh ...`.
+- Unix `bash -c`/`bash -lc` and `env VAR=...` wrappers around `busted` and
+  `luacheck` keep the wrapper or environment setup raw while applying `rtk` to
+  the noisy inner tool. Complex shell control flow, pipes, redirects, and syntax
+  checks such as `bash -n` are left alone.
 - Direct and wrapped PowerShell `Select-String`/`sls` becomes `rtk grep -n` for
   simple `-Path`/`-Pattern` forms, with optional `-Context N` mapped to `-C N`.
   Other switches are left alone.

src/rewrite.rs

@@ -12,12 +12,15 @@ pub fn suggest(command: &str) -> Option<String> {
     if command.is_empty()
         || starts_with_rtk(command) && preferred_rtk_command(command)
         || is_preferred_pwsh_wrapper(command)
+        || is_preferred_bash_wrapper(command)
     {
         return None;
     }
 
     direct_powershell_redirect(command)
         .or_else(|| powershell_redirect(command))
+        .or_else(|| env_redirect(command))
+        .or_else(|| bash_redirect(command))
         .or_else(|| posix_redirect(command))
         .or_else(|| rg_redirect(command))
         .or_else(|| safe_external_rtk_rewrite(command))
@@ -56,6 +59,7 @@ fn preferred_rtk_command(command: &str) -> bool {
                 | "curl"
         )
     ) || is_preferred_pwsh_wrapper(command)
+        || is_preferred_bash_wrapper(command)
 }
 
 fn starts_with_rtk(command: &str) -> bool {
@@ -146,6 +150,23 @@ fn is_preferred_pwsh_wrapper(command: &str) -> bool {
     })
 }
 
+fn is_preferred_bash_wrapper(command: &str) -> bool {
+    if starts_with_rtk(command) {
+        return false;
+    }
+    if tokenize(command)
+        .first()
+        .is_none_or(|token| command_name(&token.text) != "bash")
+    {
+        return false;
+    }
+
+    inner_bash_command(command).is_some_and(|(_, inner)| {
+        let tokens = tokenize(&inner);
+        find_test_tool_invocation(&tokens).is_some_and(|(_, _, _, already_rtk)| already_rtk)
+    })
+}
+
 fn inner_powershell_command(command: &str) -> Option<String> {
     let tokens = tokenize(command);
     if !tokens
@@ -167,6 +188,25 @@ fn inner_powershell_command(command: &str) -> Option<String> {
     Some(inner)
 }
 
+fn inner_bash_command(command: &str) -> Option<(String, String)> {
+    let tokens = tokenize(command);
+    if tokens
+        .first()
+        .is_none_or(|token| command_name(&token.text) != "bash")
+    {
+        return None;
+    }
+
+    let command_token = tokens.iter().position(|token| {
+        matches!(token.text.as_str(), "-c" | "-lc" | "-cl")
+            || token.text.starts_with('-') && token.text.contains('c') && !token.text.contains('n')
+    })?;
+    let option = tokens[command_token].text.clone();
+    let start = tokens.get(command_token + 1)?.start;
+    let inner = strip_outer_quotes(command[start..].trim()).to_string();
+    Some((option, inner))
+}
+
 fn strip_outer_quotes(value: &str) -> &str {
     let bytes = value.as_bytes();
     if bytes.len() >= 2
@@ -209,6 +249,117 @@ fn contains_output_redirection(command: &str) -> bool {
     false
 }
 
+fn env_redirect(command: &str) -> Option<String> {
+    let had_rtk_prefix = strip_rtk_prefix(command).is_some();
+    let without_rtk = strip_rtk_prefix(command).unwrap_or(command);
+    let tokens = tokenize(without_rtk);
+    if tokens
+        .first()
+        .is_none_or(|token| command_name(&token.text) != "env")
+    {
+        return None;
+    }
+
+    let mut index = 1;
+    while tokens
+        .get(index)
+        .is_some_and(|token| is_env_assignment(&token.text))
+    {
+        index += 1;
+    }
+    if index == 1 || index >= tokens.len() {
+        return None;
+    }
+
+    let (command_index, tool_index, tool, already_rtk) = find_test_tool_invocation(
+        &tokens[index..],
+    )
+    .map(|(command_index, tool_index, tool, already_rtk)| {
+        (command_index + index, tool_index + index, tool, already_rtk)
+    })?;
+    if command_index != index || already_rtk && !had_rtk_prefix {
+        return None;
+    }
+    if tokens[tool_index + 1..]
+        .iter()
+        .any(|token| matches!(token.text.as_str(), "|" | ";"))
+    {
+        return None;
+    }
+
+    let assignments = tokens[1..index]
+        .iter()
+        .map(|token| token.text.as_str())
+        .collect::<Vec<_>>()
+        .join(" ");
+    let args = join_args(&tokens[tool_index + 1..]);
+    Some(format!("env {assignments} rtk {tool}{args}"))
+}
+
+fn bash_redirect(command: &str) -> Option<String> {
+    let had_rtk_prefix = strip_rtk_prefix(command).is_some();
+    let without_rtk = strip_rtk_prefix(command).unwrap_or(command);
+    let (option, inner) = inner_bash_command(without_rtk)?;
+    let rewritten = shell_inner_test_tool_redirect(&inner)?;
+    if rewritten == inner && !had_rtk_prefix {
+        return None;
+    }
+    Some(format!(
+        "bash {option} {}",
+        quote_bash_command_arg(&rewritten)
+    ))
+}
+
+fn shell_inner_test_tool_redirect(inner: &str) -> Option<String> {
+    if shell_inner_has_unsupported_control(inner) {
+        return None;
+    }
+    let tokens = tokenize(inner);
+    let (command_index, tool_index, tool, already_rtk) = find_test_tool_invocation(&tokens)?;
+    if tokens[..command_index]
+        .iter()
+        .any(|token| !is_env_assignment(&token.text))
+    {
+        return None;
+    }
+
+    let prefix = inner[..tokens[command_index].start].trim_end();
+    let args = join_args(&tokens[tool_index + 1..]);
+    let mut rewritten = String::new();
+    if !prefix.is_empty() {
+        rewritten.push_str(prefix);
+        rewritten.push(' ');
+    }
+    rewritten.push_str("rtk ");
+    rewritten.push_str(&tool);
+    rewritten.push_str(&args);
+    if already_rtk && rewritten == inner {
+        return Some(inner.to_string());
+    }
+    Some(rewritten)
+}
+
+fn shell_inner_has_unsupported_control(inner: &str) -> bool {
+    inner.contains('\n')
+        || inner.contains('|')
+        || inner.contains("&&")
+        || inner.contains("||")
+        || inner.contains('<')
+        || inner.contains('>')
+        || inner.contains(';')
+}
+
+fn is_env_assignment(value: &str) -> bool {
+    let Some((name, _)) = value.split_once('=') else {
+        return false;
+    };
+    !name.is_empty()
+        && name
+            .chars()
+            .all(|ch| ch == '_' || ch.is_ascii_alphanumeric())
+        && !name.as_bytes()[0].is_ascii_digit()
+}
+
 fn content_redirect(command: &str) -> Option<String> {
     let tokens = tokenize(command);
     if !tokens
@@ -334,17 +485,22 @@ fn test_tool_redirect(inner: &str) -> Option<String> {
 }
 
 fn find_test_tool(tokens: &[Token]) -> Option<(usize, String)> {
+    let (_, tool_index, tool, _) = find_test_tool_invocation(tokens)?;
+    Some((tool_index, tool))
+}
+
+fn find_test_tool_invocation(tokens: &[Token]) -> Option<(usize, usize, String, bool)> {
     for (index, token) in tokens.iter().enumerate() {
         let name = command_name(&token.text);
         if matches!(name.as_str(), "busted" | "luacheck") {
-            return Some((index, name));
+            return Some((index, index, name, false));
         }
         if name == "rtk"
             && let Some(next) = tokens.get(index + 1)
         {
             let next_name = command_name(&next.text);
             if matches!(next_name.as_str(), "busted" | "luacheck") {
-                return Some((index + 1, next_name));
+                return Some((index, index + 1, next_name, true));
             }
         }
     }
@@ -1102,6 +1258,10 @@ fn quote_powershell_command_arg(value: &str) -> String {
     format!("'{}'", value.replace('\'', "''"))
 }
 
+fn quote_bash_command_arg(value: &str) -> String {
+    format!("'{}'", value.replace('\'', r#"'\''"#))
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;