Amnesic Shell

A stealthy, amnesic AI agent running securely inside a Linux terminal. 100% Keyless, zero footprint, and highly paranoid.

What is Amnesic Shell

Amnesic Shell is a terminal-based assistant built for privacy and stealth. Designed for live boot Kali Linux environments (via VeraCrypt containers), it leaves absolutely zero footprint on the host system.

Powered entirely by tgpt (routing through free providers like Pollinations, Phind, and DuckDuckGo), it operates with a 100% Keyless Architecture. You never need to register, log in, or provide an API key.

Key Features

• Zero Trace (In-Memory Bridge): Conversation history lives exclusively in RAM and vanishes instantly upon exit. No configs or logs are written to disk.
• 100% Keyless: No Groq or OpenAI API keys required. It dynamically falls back between free LLM endpoints.
• Paranoid Command Execution: The AI can suggest Linux terminal commands. Every command is paused and requires explicit /dev/tty user consent (y/N) before running.
• Anti-Prompt Injection: Tool outputs (e.g., from nmap or cat) are strictly truncated and wrapped in system warnings to prevent rogue data from manipulating the AI.
• Interactive REPL & Piped Context: Chat interactively or pipe files directly into the agent's brain (cat file | python3 amnesic_shell.py).

---

🚀 Setup & Usage

Prerequisites:

• Python 3.8+ (No pip install required)
• tgpt binary installed in your PATH or placed in the same directory.

# Clone the repository
git clone https://github.com/cadakerem/amnesic-shell.git
cd amnesic-shell

# Install tgpt (Linux/macOS)
curl -sSL https://raw.githubusercontent.com/aandrew-me/tgpt/main/install | bash -s /usr/local/bin

1. Interactive Mode

Launch the Ghost AI console to start chatting securely:

python3 amnesic_shell.py

2. Hybrid Piped Mode

Pipe any file, log, or command output directly into the agent. It will analyze the data in-memory and then drop you into an interactive session:

nmap -sV 192.168.1.0/24 | python3 amnesic_shell.py

---

🏗️ Architecture Overview

[User Input / Piped Context]
              |
[tgpt Keyless API Router]  <-- Anonymous LLM (Pollinations, Phind, etc.)
              |
[Command Suggested?]
  +|| Yes ||> [Explicit y/N Consent via /dev/tty] 
  -                +|| Approved ||> [Execute] ||> [Sanitize Output] ||(loop)
  -                L|| Denied   ||> [Skip]
  L|| No  ||> [Final Answer Displayed to User]

---

🛡️ Privacy & OPSEC Notes

Amnesic Shell does not collect telemetry. However, standard OPSEC rules apply:

• Network Routing: For maximum anonymity, the agent routes traffic through Tor if available (127.0.0.1:9050). It forces ALL_PROXY environment variables into the tgpt engine.
• Kill Switch: Application-level proxying is not enough to prevent DNS leaks or raw socket leaks. Always use a transparent proxy with iptables rules that enforce a strict kill switch.

---

⚠️ Known Limitations (Edge Cases)

• Context Window (Token Budget): Amnesic Shell uses a sliding window memory limit (~12,000 characters) to prevent runaway context bloat. However, since many free LLM providers (via tgpt) have varying context sizes (2K-4K tokens), large chained terminal outputs may still occasionally hit token limits depending on the provider currently in use.
• Orphaned Tool Outputs: When memory is severely pruned, the system drops the oldest conversational turns safely. However, if a massive terminal output is at the front of the queue, the agent may retain the output but lose the initial reasoning (the conversational context) of why it decided to run that specific command.

---

Inspiration & Attribution

This project stands on the shoulders of giants:

• tgpt: The core engine enabling our 100% keyless, zero-login LLM routing. Huge thanks to their work on maintaining access to free AI endpoints.
• can1357/oh-my-pi: The Ghost AI (in-memory context bridging and isolated agent loop) architecture is deeply inspired by this project. While oh-my-pi is a massive Rust-based ecosystem, amnesic-shell takes its architectural ethos and distills it down into a dependency-free, zero-footprint Python implementation designed for live amnesic environments.

🧑‍💻 Developer & Contributions

Developed by Kerem Barbaros Karnabat (@cadakerem).

Note on Repository Structure: This lightweight shell interface is completely self-contained within its main Python/C files. Command definitions and parsers are separated into logical modules to allow rapid extension and compilation for target environments.

Contributions, issues, and feature requests are welcome! Feel free to check the Issues page.

📜 License

This project is licensed under the MIT License.