{"id":25738794,"url":"https://github.com/md-talim/codecrafters-shell-java","last_synced_at":"2026-02-19T09:32:47.883Z","repository":{"id":279068771,"uuid":"937116235","full_name":"Md-Talim/codecrafters-shell-java","owner":"Md-Talim","description":"Built my own shell to understand how terminals work under the hood.","archived":false,"fork":false,"pushed_at":"2025-04-05T15:25:07.000Z","size":59,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-12T15:42:49.984Z","etag":null,"topics":["build-your-own-x","java","shell"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Md-Talim.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-22T11:26:45.000Z","updated_at":"2025-05-23T03:43:11.000Z","dependencies_parsed_at":"2025-02-23T15:34:45.421Z","dependency_job_id":"e3e2992a-d1fd-4e22-8c54-d58d41516fd9","html_url":"https://github.com/Md-Talim/codecrafters-shell-java","commit_stats":null,"previous_names":["md-talim/codecrafters-shell-java"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Md-Talim/codecrafters-shell-java","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Md-Talim%2Fcodecrafters-shell-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Md-Talim%2Fcodecrafters-shell-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Md-Talim%2Fcodecrafters-shell-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Md-Talim%2Fcodecrafters-shell-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Md-Talim","download_url":"https://codeload.github.com/Md-Talim/codecrafters-shell-java/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Md-Talim%2Fcodecrafters-shell-java/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29609524,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T06:47:36.664Z","status":"ssl_error","status_checked_at":"2026-02-19T06:45:47.551Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["build-your-own-x","java","shell"],"created_at":"2025-02-26T07:34:59.122Z","updated_at":"2026-02-19T09:32:47.866Z","avatar_url":"https://github.com/Md-Talim.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![progress-banner](https://backend.codecrafters.io/progress/shell/eb3ebe86-ed97-4aea-bb51-c81237eae9c0)](https://app.codecrafters.io/users/codecrafters-bot?r=2qF)\n\n# Build Your Own Shell\n\nThis project is a custom implementation of a POSIX-compliant shell built in Java. It interprets shell commands, runs external programs, and supports built-in commands like `cd`, `pwd`, `echo`, and more. The shell also includes features like command parsing, redirection, and autocompletion.\n\nThis project is part of the [\"Build Your Own Shell\" Challenge](https://app.codecrafters.io/courses/shell/overview) by Codecrafters. It is a great way to learn about how shells work internally and practice advanced Java programming concepts.\n\n\n## 📑 Table of Contents\n\n- [Build Your Own Shell](#build-your-own-shell)\n  - [📑 Table of Contents](#-table-of-contents)\n  - [📌 What This Project Does](#-what-this-project-does)\n  - [⚙️ How to Set Up and Run](#️-how-to-set-up-and-run)\n    - [Prerequisites](#prerequisites)\n    - [Installation](#installation)\n    - [Usage](#usage)\n  - [✨ Key Features](#-key-features)\n  - [🔍 How It Works Internally](#-how-it-works-internally)\n  - [🧰 Technologies Used](#-technologies-used)\n  - [📁 Folder and File Structure](#-folder-and-file-structure)\n  - [💡 Challenges \\\u0026 Lessons Learned](#-challenges--lessons-learned)\n    - [Challenges](#challenges)\n    - [Lessons Learned](#lessons-learned)\n  - [🛠️ Why I Built This Project](#️-why-i-built-this-project)\n\n\n## 📌 What This Project Does\n\nThis project implements a shell that:\n\n- Accepts user input to execute commands.\n- Supports built-in commands like `cd`, `pwd`, `echo`, and `exit`.\n- Runs external programs by searching for executables in the system's `PATH`.\n- Handles input/output redirection (e.g., `\u003e`, `\u003e\u003e`, `2\u003e`).\n- Provides autocompletion for commands and executables.\n\nThe purpose of this project is to understand how shells work and practice building a complex system from scratch.\n\n\n## ⚙️ How to Set Up and Run\n\n### Prerequisites\n\n- **Java 23**: Ensure you have Java 23 installed.\n- **Maven**: Install Maven for building the project.\n- **Linux Environment**: The shell uses POSIX features, so it works best on Linux.\n\n### Installation\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/Md-Talim/codecrafters-shell-java.git\n   cd codecrafters-shell-java\n   ```\n\n2. Build the project using Maven:\n   ```bash\n   mvn clean package\n   ```\n\n3. Run the shell:\n   ```bash\n   ./your_program.sh\n   ```\n\n### Usage\n\n- You'll see a prompt like `$`.\n- Enter commands like `pwd`, `echo Hello`, or `ls`.\n- Use `Ctrl+D` or `exit` command to exit the shell.\n\n\n## ✨ Key Features\n\n- **Built-in commands**\n  Supports common commands like:\n  - `cd`: Change directory\n  - `pwd`: Print working directory\n  - `echo`: Print text\n  - `exit`: Exit the shell\n  - `type`: Show whether a command is built-in or external\n\n- **External command support**\n  If a command isn’t built-in, the shell searches the system `PATH` and runs it using Java’s `ProcessBuilder`.\n\n- **I/O redirection**\n  Redirect output and errors using:\n  - `\u003e` (overwrite)\n  - `\u003e\u003e` (append)\n  - `2\u003e` (redirect stderr)\n\n- **Autocompletion**\n  Press `Tab` to auto-complete command names or see suggestions.\n\n- **Error handling**\n  - Displays clear error messages when commands fail or are used incorrectly\n  - Handles missing files, bad arguments, and permission issues gracefully\n  - Prevents the shell from crashing due to unexpected input or runtime errors\n\n- **Raw terminal mode**\n  Switches the terminal to raw mode to capture user input character by character—enabling advanced input behavior like autocompletion.\n\n\n## 🔍 How It Works Internally\n\nHere's a simplified look at how the shell is structured under the hood:\n\n| Component              | Role                                                                      |\n| ---------------------- | ------------------------------------------------------------------------- |\n| `Shell.java`           | The main loop that reads input, parses commands, and executes them.       |\n| `Parser.java`          | Breaks the input line into tokens, handles redirection and quoting.       |\n| `CommandRegistry`      | Registers and manages built-in commands.                                  |\n| `ExternalCommand.java` | Executes non-built-in programs via `ProcessBuilder`.                      |\n| `Redirection.java`     | Handles output and error redirection to files.                            |\n| `AutoCompleter.java`   | Provides suggestions for commands using `Tab`.                            |\n| `Termios.java`         | Enables raw terminal mode via JNA to control low-level terminal settings. |\n\n\n## 🧰 Technologies Used\n\n- **Java**: The primary programming language.\n- **Maven**: For building and managing dependencies.\n- **JNA (Java Native Access)**: For interacting with low-level terminal settings.\n- **POSIX**: For shell behavior and command execution.\n\n\n## 📁 Folder and File Structure\n\n```\nsrc/\n  main/\n    java/\n      Main.java                # Entry point of the program\n      shell/\n        Shell.java             # Core shell logic\n        command/               # Built-in commands\n        environment/           # Environment management\n        io/                    # Input/output utilities\n        parser/                # Command parsing\n        process/               # External command execution\n        terminal/              # Terminal control\n        autocomplete/          # Autocompletion logic\n```\n\n**Key files:**\n- `Main.java`: Starts the shell and handles user input.\n- `Shell.java`: Manages commands and execution.\n- `Parser.java`: Parses user input into commands and arguments.\n- `SystemProcessExecutor.java`: Executes external commands.\n\n\n## 💡 Challenges \u0026 Lessons Learned\n\n### Challenges\n\n1. **Command Parsing**:\n   - Handling quotes, escape characters, and redirection operators was tricky.\n\n2. **Redirection**:\n   - Managing file output and error streams required careful design.\n\n3. **Autocompletion**:\n   - Implementing a responsive and accurate autocompletion system was challenging.\n\n4. **Terminal Control**:\n   - Disabling echo and enabling raw mode required low-level terminal manipulation.\n\n### Lessons Learned\n\n- Gained a deep understanding of how shells work.\n- Improved skills in Java, especially working with `ProcessBuilder` and file I/O.\n- Learned about terminal control using JNA and POSIX standards.\n\n\n## 🛠️ Why I Built This Project\n\nI built this project to:\n\n- Practice advanced Java programming concepts.\n- Learn how Bash/Zsh-like shells work under the hood\n- Practice writing clean, modular, and testable Java code\n- Solve a real-world systems-level problem from scratch\n\nThis project helped me grow as a backend/systems engineer and is one of my favorite learning experiences.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmd-talim%2Fcodecrafters-shell-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmd-talim%2Fcodecrafters-shell-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmd-talim%2Fcodecrafters-shell-java/lists"}