tsh

Tangible Shell for finding and launching Tangible Research projects.

Whats tsh

tsh is a small command-line shell for Tangible tools. It can launch Halgorithem in a disposable Docker sandbox and scan the TangibleResearch GitHub organization for new projects, showing each repo with the best run command it can find.

How does tsh Work

tsh checks for internet access, then routes commands through a small local shell. For Halgorithem, it starts a lightweight Python Docker container, clones the repo from GitHub, installs the verifier dependencies, patches the sandbox to use lightweight local scoring, and opens tui.py.

For project discovery, tsh scans public repositories in the TangibleResearch GitHub organization, reads common project files like README.md, pyproject.toml, package.json, Cargo.toml, go.mod, and main.py, then lists how each project appears to run.

Key Features

• Launches Halgorithem in Docker
  tsh keeps the Halgorithem runtime isolated from your local Python environment.

• Simple shell command
  Run connect Halgo from the interactive shell or pass it directly as a command.

• OpenAI API key passthrough
  If OPENAI_API_KEY is available in your environment, tsh passes it into the sandbox container.

• Scans TangibleResearch projects
  tsh can list all active public projects in the org and show the best detected install or run command.

• Future-project friendly
  New repositories are discovered from GitHub at runtime, so tsh does not need a hardcoded list to notice them.

Requirements

• Python 3.11 or newer
• Docker Desktop or Docker CLI
• Internet access for scanning GitHub, cloning Halgorithem, and installing packages
• Optional GITHUB_TOKEN for higher GitHub API limits

Installation

To run tsh, follow these steps:

1. Create a virtual environment:

   python -m venv venv

2. Activate the virtual environment:

   source venv/bin/activate

3. Install the required modules:

   pip install -r requirements.txt

4. Run tsh:

   python main.py

5. Connect to Halgorithem:

   connect Halgo

6. Scan TangibleResearch projects:

   projects

You can also launch Halgorithem directly:

python main.py connect Halgo

CLI Usage

Interactive shell:

python main.py

Direct command:

python main.py connect Halgo

Scan TangibleResearch:

python main.py projects

Equivalent scan command:

python main.py scan org

Scan another GitHub organization:

python main.py projects SomeOrgName

Exit the shell:

exit

Notes

• tsh does not install Halgorithem on your machine.
• The Docker sandbox is removed after the session closes.
• Halgorithem dependencies are installed inside the container each time tsh launches the sandbox.
• Project run commands are best-effort guesses from repository docs and common project files.