chopped-onions 0.1.0

An interactive TUI to search the Tor network for .onion links by keyword.

🧅 chopped onions

Search the Tor network for .onion links — right from your terminal.

A fast, colorful TUI that scrapes multiple onion search engines in parallel over Tor, ranks the results against your query, and copies any link to your clipboard with a single keypress. Privacy-first by design: every request is forced through Tor, with a fresh circuit per search.

---

✨ Features

• 🔎 Parallel onion search — queries Torch, Tordex, Tor66 and OnionLand Search at once, then merges, de-duplicates and ranks the hits.
• 🧅 100% over Tor — fail-closed networking: if traffic can't be routed through Tor, it refuses to run rather than leaking to the clearnet.
• 🔁 Fresh circuit per search — stream isolation gives each search its own unlinkable Tor circuit.
• 🕵️ Anti-fingerprinting — sends stock Tor-Browser-style headers, no cookies, no Referer, nothing identifying.
• ⌨️ Keyboard-driven — type, hit Enter, arrow up/down to pick, Enter to copy the address to your clipboard.
• 🧠 Smart query syntax — AND, OR, "exact phrases" and -exclusions.
• 🎨 5 themes — onion, matrix, amber, synthwave, ice.
• ⚙️ Configurable — proxy, timeouts, engines, colors, clipboard behavior, all in one TOML file.
• 🛡️ Built-in safety self-test — chopped-onions --check confirms you're actually exiting through Tor.

🎨 Themes

synthwave	matrix

---

📦 Installation

Prerequisite: you need Tor running locally with a SOCKS proxy on 127.0.0.1:9050. See Setting up Tor below.

Option 1 — pipx (recommended)

pipx installs the app into its own isolated environment and puts the command on your PATH:

pipx install git+https://github.com/Thatkidtk/chopped-onions
chopped-onions

Option 2 — pip

pip install git+https://github.com/Thatkidtk/chopped-onions
chopped-onions

Option 3 — from source

git clone https://github.com/Thatkidtk/chopped-onions
cd chopped-onions
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/chopped-onions

Or just run the bundled launcher, which will start Tor for you if it isn't already up:

./onions

---

🧅 Setting up Tor

chopped onions talks to Tor's SOCKS proxy — it does not ship or embed Tor itself.

macOS (Homebrew)

brew install tor
brew services start tor          # runs Tor in the background on 127.0.0.1:9050

Debian / Ubuntu

sudo apt install tor
sudo systemctl enable --now tor

Arch

sudo pacman -S tor
sudo systemctl enable --now tor

Already have Tor Browser? It exposes a SOCKS proxy on port 9150 while open. Set port = 9150 in your config and you're good to go.

Verify everything is wired up correctly:

chopped-onions --check
# ✓ Tor OK — exit node 185.220.101.25

---

🚀 Usage

Launch the app, type a query, press Enter:

chopped-onions

Key	Action
type + Enter	run the search
↓ (in search bar)	jump into the results list
↑ / ↓	move the selection
Enter (on a result)	copy the .onion link to clipboard
Ctrl+O	open the selected link in a browser (if configured)
Esc	return to the search bar
Ctrl+L	clear
Ctrl+R	re-check the Tor connection
Ctrl+C	quit

Search syntax

Mix these freely. The cleaned words are sent to the engines; the operators filter and rank the results locally:

Pattern	Meaning
email privacy	AND — both words boost a result
"secure email"	exact phrase (required)
email OR mail	either (also email|mail)
market -scam	exclude results containing scam

Example: "secure email" privacy OR anonymity -scam

---

🛡️ Staying safe & anonymous

chopped onions is built to be safe by default, but anonymity is a practice, not a checkbox. Read this.

What the tool does for you

• Fail-closed routing. Every request goes through the Tor SOCKS proxy using socks5h (remote DNS), so .onion names — and all lookups — are resolved by Tor, never your local resolver. If the proxy is missing or misconfigured, the app refuses to make the request instead of silently falling back to a direct, deanonymizing connection.
• Per-search circuit isolation. Each search uses random SOCKS credentials, so Tor builds a fresh, unlinkable circuit every time. One search can't be trivially correlated with the next.
• A low-information fingerprint. Requests carry stock Tor-Browser-style headers. No cookies are stored, no Referer is sent, no custom headers identify you, and $HTTP_PROXY/system proxy env vars are ignored so routing is exactly what you configured.
• No history on disk. Your queries and results are never written to a log or history file. The only file the app writes is the config you control.

What you are responsible for

🔒 Tor hides where you connect from. It does not make you anonymous if you give yourself away.

• Browse .onion results in the Tor Browser, not a normal browser. Copying a link is safe; opening it in Chrome/Safari is not — it leaks your real IP and a rich browser fingerprint. The clipboard-copy workflow exists precisely so you can paste into Tor Browser.
• Never enter real personal info (name, email, phone, reused passwords) on hidden services. Treat everything as hostile.
• Don't log in to clearnet accounts over Tor in a way that links your identity to your Tor activity.
• Assume search results are untrusted. Onion indexes contain spam, scams, phishing clones and worse. A result appearing here is not an endorsement — verify addresses out-of-band before trusting them.
• Keep your system updated, and prefer running from a privacy-focused OS like Tails or Whonix if your threat model calls for it.
• Mind your metadata. Time-of-use patterns, writing style, and unique queries can all be de-anonymizing over time.
• Consider a bridge (obfs4) if simply connecting to Tor is sensitive where you are.

Verify it's working

Before trusting it, run the self-test — it confirms your traffic is actually exiting through the Tor network:

chopped-onions --check

You can also press Ctrl+R inside the app at any time.

---

⚙️ Configuration

A documented config file is created on first run at ~/.config/chopped-onions/config.toml:

theme = "onion"          # onion | matrix | amber | synthwave | ice

[tor]
host = "127.0.0.1"
port = 9050              # use 9150 for Tor Browser's proxy
timeout = 45
isolate_circuits = true  # fresh, unlinkable circuit per search (recommended)

[search]
max_results = 200
per_engine_limit = 100
dedupe = true

[behaviour]
copy = "url"             # "url" copies full link, "host" copies only the .onion host
open_command = ""        # e.g. "open -a 'Tor Browser' {url}" to also launch a browser
confirm_quit = false

[[engines]]              # add / disable / update engines here
name = "torch"
url = "http://torchdeedp3i2jigzjdmfpn5ttjhthh5wbmda2rr3jvqjg5p77c54dqd.onion/search?query={q}"
enabled = true
# … and tordex, tor66, onionland

💡 Onion addresses change over time. If an engine goes dark, update its address (or add your own) in the [[engines]] section — {q} is the URL-encoded query.

---

⚖️ Disclaimer

chopped onions is a research / OSINT / privacy tool. It only queries public onion search indexes — it does not crawl, host, or fetch content from the sites it lists, and indexing a link is not an endorsement of it. You are solely responsible for how you use it and for complying with the laws of your jurisdiction. Provided as-is, without warranty. See LICENSE.

🤝 Contributing

Issues and PRs welcome — new engines, themes, parsers, and packaging improvements especially. Please keep the fail-closed, Tor-only safety guarantees intact in any networking change.

📄 License

MIT © Thatkidtk